HOME BLOG
 

MAPAS API

Classe SAPO.Maps.Itineraries

As instâncias desta classe permitem obter direcções entre dois locais e apresentar automaticamente os resultados num mapa e num painel.
A diferença entre esta classe e a classe SAPO.Maps.Directions é que enquanto a última pesquisa um itinerário entre dois pontos definidos por coordenadas, SAPO.Maps.Itineraries pesquisa um itinerário entre dois pontos, definidos pelo seu nome. No caso de nomes que produzam mais do que um resultado, o utilizador pode escolher entre quais pretende obter o itinerário.
Cada instância desta classe tem associado um estado, fornecido pelo enumerado SAPO.Maps.Request.Status. A evolução entre os diferentes estados obedece ao fluxograma apresentado em SAPO.Maps.Request.Status. O objecto inicia-se no estado de STOP. No momento do pedido ao servidor este fica REQUESTING e daí podem resultar três estados possíveis, OK, em caso de sucesso, ERROR, em caso de timeout, ou CANCELED, no caso do pedido ter sido cancelado pelo utilizador. Note-se que apenas pode haver um pedido por itinerários em cada momento. Se pretender efectuar um novo pedido e o anterior ainda estiver em curso, deve ser explicitamente cancelado pelo utilizador (chamando o método cancel() da instância).

CLASS REFERENCE
QUICKLINKS
 
Construtor
Construtor Descrição

SAPO.Maps.Itineraries(map?:SAPO.Maps.Map, panel?:String|DOM Element, options?:Object)

Cria uma nova instância de SAPO.Maps.Itineraries. Se for indicada uma instância de mapa, o trajecto será desenhado sobre map. O parâmetro panel é o identificador ou referência para um elemento DOM, no qual será apresentada a descrição do itinerário (se for fornecido). options é um objecto com as seguintes chaves:

  • border:Object: Indica sobre o portview a área disponível para abrir o popup. Este objecto tem as seguintes chaves:
    • left:Integer: Especifica a margem esquerda.
    • top:Integer: Especifica a margem superior.
    • right:Integer: Especifica a margem direita.
    • bottom:Integer: Especifica a margem inferior.
  • language:String: Especifica o idioma em que os resultados serão apresentados. Os valores possíveis são: ‘pt’ ou ‘en’.
Métodos
Método Retorno Descrição

getItinerary(from:String, to:String, options:Object)

void

Inicia um novo pedido para obter um itinerário entre from e to.

Para que um novo pedido seja iniciado, o pedido pendente (caso exista) deve ser cancelado, usando o método cancel().  Caso exista um pedido pendente e não seja cancelado, é lançada uma excepção.

As opções são especificadas em options, um objecto com as seguintes chaves:

  • language:String: O idioma em que será apresentada a descrição do itinerário. Os valores possíveis são “pt” ou “en”.
  • mode:String: O modo de itinerário a obter. Os valores possíveis são: “fastest”, “shortest” ou “walk”.

Após a chamada deste método é feita uma pesquisa para encontrar candidatos ao local de partida. Quando esta pesquisa estiver concluída (disparado o evento startingPOIS) e se for encontrado mais do que um candidato, um deles tem que ser seleccionado. Após estar encontrada a partida (é disparado o evento startSelected), o mesmo procedimento tem que ser cumprido para encontrar o local de chegada (são disparados os eventos endingPOIS e endSelected). Só depois dos locais de partida e chegada estarem identificados é que o cálculo de um itinerário entre elas pode ser efectuado.

Este método pode disparar ainda os seguintes eventos

  • noresults: Caso não sejam encontrados candidatos a local de partida. O estado do objecto é colocado como STOPED.

getStatus()

SAPO.Maps.Request.Status

Devolve o estado do pedido. Os valores possíveis são:

  • STOP: Não existe nenhum pedido em curso. Este é o estado inicial.
  • OK: O último pedido foi concluído com sucesso.
  • ERROR: Ocorreu um erro com o último pedido.
  • REQUESTING: Encontra-se um pedido em curso.
  • CANCELED: O pedido que estava em curso foi cancelado.

getStartingPOIS()

Array<SAPO.Maps.Poi>

Retorna o conjunto de POIs candidatos a local de partida do itinerário. Se o local de partida já tiver sido escolhido, o array devolvido contém apenas uma posição com o POI escolhido. Deve ser chamado após ser disparado o evento startingPOIS. Se o pedido ainda estiver em curso e os resultados não disponíveis, é devolvido null.

getEndingPOIS()

Array<SAPO.Maps.Poi>

Retorna o conjunto de POIS candidatos a local de chegada do itinerário. Se o local de chegada já tiver sido escolhido, o array devolvido contém apenas uma posição com o POI escolhido. Deve ser chamado após ser disparado o evento endingPOIS. Se o pedido ainda estiver em curso e os resultados não disponíveis, é devolvido null.

goToPage(page:Integer)

void

Este método posiciona os resultados na página passada por parâmetro. Este método só deverá ser evocado na fase de geocoding, após os eventos de startingPOIS e endingPOIS serem disparados.

selectStartPOI(idx:Integer)

void

Selecciona o POI com índice igual a idx como ponto de partida do itinerário. Dispara o evento startSelected. Após a partida ter sido escolhida, vai ser realizada uma pesquisa pelos candidatos a local de chegada.

Se apenas existir um resultado este é seleccionado automaticamente, disparando os eventos startingPOIS e startSelected, iniciando depois a pesquisa por candidatos a locais de chegada.

selectEndPOI(idx:Integer)

void

Selecciona o POI com índice igual a idx como ponto de chegada do itinerário. Dispara o evento endSelected. Após a chegada ter sido escolhida, é feito o pedido de um percurso entre a partida e a chegada.

Se apenas existir um resultado este é seleccionado automaticamente, disparando os eventos endingPOIS e endSelected.

clear()

void

Limpa os resultados do mapa e do painel, se estes tiverem sido fornecidos no construtor.

Apenas deve ser chamado quando não se encontra um pedido ao servidor em curso (estado OK, STOP, ERROR, CANCELED). Se chamado enquanto um pedido está em curso é lançada uma excepção.

cancel()

void

Se existir algum pedido em curso, este método cancela-o, podendo ser iniciado um novo pedido. A execução deste método dispara o evento canceled e coloca o estado do objecto como CANCELED.

getDirections()

SAPO.Maps.Directions

Se o estado do pedido for SAPO.Maps.Request.Status.OK, este método retorna o objecto SAPO.Maps.Directions que contém os dados do itinerário encontrado.

getSearch()

SAPO.Maps.Search

Devolve o objecto search usado para procurar POIS.

selectResult(idx:Integer)

void

Mostra informação detalhada (abre o popup) sobre o resultado com índice idx.

unselectResult(idx:Integer)

void

Esconde os detalhes sobre o resultado do índice idx.

getResultSelected()

Integer

Devolve um inteiro que indica qual o índice seleccionado. Se nenhum estiver seleccionado, devolve null.

registerEvent(eventType:SAPO.Maps.Search.EVENT_TYPES, context:Object, func:Function)

void

Regista a função func como listener do evento do tipo eventType. O callback func será chamado com o contexto context.

unRegisterEvent(eventType:SAPO.Maps.Search.EVENT_TYPES, context:Object, func:Function)

Boolean

Remove func como listener de eventos do tipo eventType. Retorna true ou false conforme o sucesso da operação.
Eventos
Evento Descrição

startingPOIS(itinerary:SAPO.Maps.Itineraries)

Disparado quando os POIs possíveis para local de partida estão disponíveis.

endingPOIS(itinerary:SAPO.Maps.Itineraries)

Disparado quando os POIs possíveis para local de chegada estão disponíveis.

complete(directions:SAPO.Maps.Directions)

Disparado quando o itinerário já se encontra disponível.

error(itinerary:SAPO.Maps.Itineraries)

Disparado quando ocorre um erro no processamento do pedido.

timeout(itinerary:SAPO.Maps.Itineraries)

Disparado quando não há resposta ao pedido.

startSelected(poi:SAPO.Maps.Poi, idx:Integer)

Disparado quando o ponto de partida é seleccionado.

endSelected(poi:SAPO.Maps.Poi, idx:Integer)

Disparado quando o ponto de chegada é seleccionado.

clean(itinerary:SAPO.Maps.Itineraries)

Disparado quando o itinerário e a sua descrição são limpos do mapa e do painel.

canceled(itinerary:SAPO.Maps.Itineraries)

Disparado quando há cancelamento do pedido.

noresults(itinerary:SAPO.Maps.Itineraries, start:Boolean)

Disparado quando não são encontrados resultados para o local de partida ou de chegada. O parâmetro start indica se foi na partida ou na chegada que não se encontraram resultados.

itinerarynotfound(itinerary:SAPO.Maps.itineraries)

Disparado quando não é encontrado um itinerário entre os pontos de início e fim seleccionados.

resultSelect(idx: Integer, page:Integer)

Disparado quando um dos valores da listagem do itinerário é seleccionado. Poderá ser a listagem de possíveis candidatos ou a apresentação dos vários passos do itinerário.

resultUnselect(idx: Integer, page:Integer)

Disparado quando um dos valores da listagem do itinerário é desseleccionado. Poderá ser a listagem de possíveis candidatos ou a apresentação dos vários passos do itinerário.