場所 (C++)

概要

Places APIによって、ユーザーは興味のある場所やポイントを発見し、住所や連絡先情報などの詳細を見ることができます。Places APIはまた、場所やカテゴリーの管理を容易にし、ユーザーがそれらを保存したり削除したりできるようにします。

場所の定義

場所とは、お気に入りのレストランや公園、誰かの家など、興味のある場所のことです。QPlace オブジェクトは、その場所に関するさまざまな情報のコンテナとして機能することで、場所を表します。

この情報は大きく2つに分類できる。

  • 詳細
  • リッチコンテンツ

場所の詳細は、名前、場所、連絡先などの場所のプロパティで構成されています。検索中に場所が返されると、これらの詳細が入力されます。帯域幅を節約するために、ユーザーが興味を持っている場合は、場所ごとに個別に取得することができます場所についてのさらなる詳細が存在することがあります。QPlace::detailsFetched() 関数を使用すると、使用可能なすべての詳細情報が取得済みかどうかを確認することができ、取得済みでない場合はQPlaceManager::getPlaceDetails() を使用して取得できます。どの詳細が検索中に入力され、どの詳細が個別に取得される必要があるかは、プロバイダによって異なります。詳細はプラグインのドキュメントを参照してください。

プレイスメントのリッチコンテンツは、画像、レビュー、論説などの項目から構成されます。多くのリッチコンテンツアイテムが存在する可能性があるため、それらはプレイス詳細とは別に扱われます。それらは、QPlaceManager::getPlaceContent() を介して、ページングされた方法で取得することができます。必要であれば、コンテンツはプレイスに割り当てられ、便利なコンテナとして機能します。

共通操作

マネージャの初期化

すべてのプレース機能は、QPlaceManager インスタンスによって促進される。を作成するには、QGeoServiceProvider を指定しなければならない。QPlaceManager

//The "provider name" is used to select a particular provider
QGeoServiceProvider *provider = new QGeoServiceProvider("provider name");
QPlaceManager *manager = provider->placeManager();

検索を実行するには、QPlaceSearchRequest を作成し、検索語や検索センターなど、必要な検索パラメーターを設定するだけでよい。

//instantiate request and set parameters
QPlaceSearchRequest searchRequest;
searchRequest.setSearchTerm("ice cream");
searchRequest.setSearchArea(QGeoCircle(QGeoCoordinate(12.34, 56.78)));

//send off a search request
/*QPlaceSearchReply * */ searchReply = manager->search(searchRequest);

//connect a slot to handle the reply
connect(searchReply, &QPlaceSearchReply::finished, this, &RequestHandler::handleSearchReply);

リクエストは非同期操作なので、リクエストの完了を処理するスロットが必要です。ハンドラでは、エラーがないことと、検索結果のタイプがプレースであることをチェックする。もしそうであれば、その場所のコアの詳細を取得することができます。スロットの最後に、リプライを削除します。

voidhandleSearchReply() {if(searchReply->error()==QPlaceReply::NoError) {for(constQPlaceSearchResult&result: searchReply->results()) {if(result.type()==QPlaceSearchResult::PlaceResult) { if (result.type() ==::PlaceResult)              QPlaceResultplaceResult=result;                qDebug() << "Name: " << placeResult.place().name();
                qDebug() << "Coordinate " << placeResult.place().location().coordinate().toString();
                qDebug() << "Street: " << placeResult.place().location().address().street();
                qDebug() << "Distance: " << placeResult.distance();
            } } searchReply->deleteLater();//返信を破棄するsearchReply=nullptr; }

注意:選択したプラグインバックエンドによっては、検索結果に、場所ごとに取得できる詳細情報を持つ場所が含まれることがあります。これらの詳細を取得するには、場所の詳細を取得するを参照してください。

推奨事項

QPlaceSearchRequest::setRecommendationId()で場所IDを指定することで、おすすめスポットを取得することができます。指定された場所に似た場所が検索されます。

ページング

プラグインがページングをサポートしている場合、検索リクエストに limit パラメータを指定することができます。

QPlaceSearchRequest searchRequest;
searchRequest.setLimit(15); //specify how many results are to be retrieved.

場所の詳細の取得

検索リクエストから返された場所には、フェッチできる詳細があるかもしれません。以下は、さらなる詳細があるかどうかをチェックする方法と、もしあればそれを要求する方法を示しています。

if (!place.detailsFetched()) {
    /*QPlaceDetailsReply * */ detailsReply = manager->getPlaceDetails(place.placeId());
    connect(detailsReply, &QPlaceDetailsReply::finished, this, &RequestHandler::handleDetailsReply);
}
    ...
    ...
void handleDetailsReply() {
    QPlace place;
    if (detailsReply->error() == QPlaceReply::NoError)
        place = detailsReply->place();

    detailsReply->deleteLater(); //discard reply
    detailsReply = nullptr;
}

リッチコンテンツの取得

画像やレビューのようなリッチコンテンツはマネージャーを通して取得され、必要であれば場所に割り当てられます。

QPlaceContentRequest request;
request.setContentType(QPlaceContent::ImageType);
request.setPlaceId(place.placeId());
request.setLimit(5);
/*QPlaceContentReply * */ contentReply = manager->getPlaceContent(request);
connect(contentReply, &QPlaceContentReply::finished, this, &RequestHandler::handleImagesReply);

コンテンツリクエストは以下のように処理できます。

voidhandleImagesReply() {if(contentReply->error()== ==::NoError) { const auto content = contentReply->error() QPlaceReplyif (contentReply->error() ==::NoError) {const autocontent=  contentReply->content();for(autoiter=content.cbegin(),end=content.cend(); iter!=end;++iter) { {for(autoiter=content.cbegin(),end=content.cend(); iter!=end;++iter)            qDebug() << "Index: " << iter.key();
           QPlaceImageimage=iter.value();            qDebug() << image.url();
            qDebug() << image.mimeType();
        }//インデックスが関係ない場合の代替案 for(const QPlaceImage &image: contentReply->content()) {//インデックスが関係ない場合の代替案            qDebug() << image.url();
            qDebug() << image.mimeType();
        }//コンテンツを、そのコンテンツが属する場所に割り当てることができます。 //場所オブジェクトは、 すでに取得された //コンテンツを 取得するためのコンテナとして機能しますplace.insertContent(contentReply->request().contentReply->request().contentType(),  contentReply->content()); place.setTotalContentCount(contentReply->request().contentType(),  contentReply->totalCount()); } contentReply->deleteLater(); contentReply=nullptr; }

QPlaceContentReply の結果はQPlaceContent::Collection であり、これは本質的にQMap<int,QPlaceContent> であることに注意することが重要である。この場合のキーint はコンテンツのインデックスであり、値はコンテンツそのものである。Contentの実装方法によって、次のようにContent Typeを変換することができます。

QPlaceImage image = content; //provided that 'content' has a type QPlace::ImageType

QPlaceContent::Collection 、コンテンツとそのサブタイプ間の変換の使用は、レビュー、画像、社説のページングの仕組みを処理するコードを簡単に共有できることを意味します。

検索サジェスチョン

検索語のサジェストの検索はプレースサーチの実行に非常に似ています。QPlaceSearchRequest 、場所検索と同じように使われます。唯一の違いは、検索語が部分的に完成した文字列に設定されることです。

QPlaceSearchRequest request;
request.setSearchTerm("piz");
request.setSearchArea(QGeoCircle(QGeoCoordinate(12.34, 56.78)));
/* QPlaceSearchSuggestion * */suggestionReply = manager->searchSuggestions(request);
connect(suggestionReply, &QPlaceSearchSuggestion::finished, this, &RequestHandler::handleSuggestionReply);

そして、リクエストが終わると、サジェストを表示するためにリプライを使うことができます。

voidhandleSuggestionReply() {if(suggestionReply->error()==QPlaceReply::NoError) {for(constQString提案: suggestionReply->suggestions())            qDebug() << suggestion;
    } suggestionReply->deleteLater();//返信を破棄suggestionReply=nullptr; }.

場所の保存

新しい場所の保存は次のように行います。QPlace インスタンスを作成し、名前、住所、座標などの情報を入力します。保存が完了したら、QPlaceManager::savePlace()を呼び出して保存を開始する。

QPlace  place;
place.setName( "Fred's Ice Cream Parlor" );

QGeoLocation location;
location.setCoordinate(QGeoCoordinate(12.34, 56.78));

QGeoAddress address;
address.setStreet("111 Nother Street");
    ...
location.setAddress(address);
place.setLocation(location);

/* QPlaceIdReply * */savePlaceReply = manager->savePlace(place);
connect(savePlaceReply, &QPlaceIdReply::finished, this, &RequestHandler::handleSavePlaceReply);

場所が保存されると、その場所の新しい識別子が返信される。

voidhandleSavePlaceReply() {if(savePlaceReply->error()==::NoError) QPlaceReply::NoError)        qDebug() << savePlaceReply->id();

    savePlaceReply->deleteLater();//返信を破棄するsavePlaceReply=nullptr; }

すでに存在する場所を保存するには、QPlace::placeId()に正しい識別子を入れなければならないことに注意してください。そうしないと、空の場合は新しい場所が作成され、識別子が正しくない場合は間違った場所が上書きされます。

場所が保存されるとき、QPlaceManager は QPlaceManager::placedAdded() またはQPlaceManager::placeUpdated() シグナルを発するかもしれません。ウェブサービスから場所にアクセスするマネージャは通常これらのシグナルを発しませんが、ローカルに保存された場所にアクセスするマネージャは通常これらのシグナルを発します。

注意点

Places APIは現在、core の詳細のみを保存するように設計されています。画像やレビューのようなリッチコンテンツや、サプライヤーやレーティングのような詳細を保存することは、サポートされていないユースケースです。通常、マネージャは保存時にこれらのフィールドを無視します。

Places APIは、以下のコアな詳細の保存のみをサポートしています:

  • 名前
  • 場所ID
  • 場所
  • 連絡先の詳細
  • アイコン
  • カテゴリー(場所を説明するタグのような名前)
  • 可視範囲

プロバイダがこれらのサブセットしかサポートしていない可能性もあります。詳しくはプラグインのドキュメントを参照してください。

レーティング、拡張属性、画像、レビュー、社説、サプライヤーなどのプロパティの保存は、Places APIではサポートされていません。

管理者間での保存

管理者間でプレイスメントを保存する場合、いくつか注意すべき点があります。例えば、あるマネージャのカテゴリは別のマネージャでは認識されないかもしれません。そのため、あるマネージャーから別のマネージャーに直接場所を保存することはできません。

典型的な方法はQPlaceManager::compatiblePlace() 関数を使用することです。これは場所のコピーを作成しますが、マネージャがサポートするデータのみをコピーします。場所の識別子のようなマネージャー固有のデータはコピーされません。新しいコピーはマネージャに保存するのに適しています。マネージャが代替識別子によるマッチングをサポートしている場合、代替識別子属性がコピーに割り当てられます(マネージャ間の場所のマッチングを参照)。

//result retrieved from a different manager)
QPlace place = manager->compatiblePlace(result.place());
saveReply = manager->savePlace(place);

場所の削除

プレイスの削除は以下のように行われます:

/* QPlaceIdReply * */removePlaceReply =  manager->removePlace(place.placeId()); connect(removePlaceReply, &); ... ...QPlaceIdReply::finished, this, &RequestHandler::handleRemovePlaceReply); ... ...voidhandleRemovePlaceReply() {if(removePlaceReply->error()== ==:NoError) QPlaceReply::NoError)        qDebug() << "Removal of place identified by"
                <<  removePlaceReply->id()<< "was successful"; removePlaceReply->deleteLater();//返信を破棄removePlaceReply=nullptr; }

プレイスが削除されると、QPlaceManagerQPlaceManager::placeRemoved() シグナルを発するかもしれない。マネージャがそうするかどうかはプロバイダ固有です。ウェブサービスからプレイスにアクセスするマネージャは、通常これらのシグナルを発しませんが、ローカルに保存されたプレイスにアクセスするマネージャは、通常これらのシグナルを発します。

カテゴリの使用

カテゴリーは場所を説明するキーワードです。例えば、「公園」、「劇場」、「レストラン」などである。公園であったり、音楽会場であったり、フェリーやバス停であったりと、1つの場所を多くのカテゴリーで表現することができます。

カテゴリーを使うには、まず初期化する必要がある。

/* QPlaceReply * */initCatReply =  manager->initializeCategories(); connect(initCatReply, &::finished,this, &Reply); Connect(initCatReply, &::finished,this, &Reply)QPlaceReply::finished, this, &RequestHandler::handleInitCatReply); ... ...voidhandleInitCatReply() {if(initCatReply->error()== ==::NoError) QPlaceReply::NoError)        qDebug() << "Categories initialized";
   その他        qDebug() << "Failed to initialize categories";

    initCatReply->deleteLater(); initCatReply=nullptr; }

カテゴリーが初期化されたら、次にこれらのカテゴリー関数を使うことができる。

トップレベルのカテゴリーを取得するために、QPlaceManager::childCategories ()関数を使用しますが、カテゴリー識別子を提供しません。

constQList<QPlaceCategory> topLevelCategories=  manager->childCategories();for(constQPlaceCategoryfor (&category: topLevelCategories)    qDebug() << category.name();

もし識別子を与えれば、カテゴリの子を取り出すことができる。

QList<QPlaceCategory> childCategories = manager->childCategories(pizza.categoryId());

カテゴリーの保存

カテゴリを保存する方法を以下に示します。

QPlaceCategoryfastFood;QPlaceCategorycategory; category.setName("ピザ");/*QPlaceIdReply */saveCategoryReply=  manager->saveCategory(category); connect(saveCategoryReply, &RequestHandler::handleSaveCategoryReply); //カテゴリーを保存することができましたQPlaceIdReplysaveCategoryReply=  manager->saveCategory(category,fastFood.categoryId()); ... ...voidhandleSaveCategoryReply() {if(saveCategoryReply->error()==::NoError) { (saveCategoryReply->error()==::NoError) {if(saveCategoryReply->error()== ::NoError) { (saveCategoryReply->error()== ::NoError) QPlaceReply::NoError) { .        qDebug() << "Saved category id =" << saveCategoryReply->id();
    } saveCategoryReply->deleteLater(); saveCategoryReply=nullptr; }

カテゴリーが保存されると、QPlaceManagerQPlaceManager::categoryAdded() またはQPlaceManager::categoryUpdated() シグナルを発するかもしれない。ウェブサービスから場所にアクセスするマネージャは、通常これらのシグナルを発しませんが、ローカルに保存された場所にアクセスするマネージャは、通常これらのシグナルを発します。

カテゴリの削除

カテゴリの削除は、プレースメントの削除とよく似ています。

/* QPlaceIdReply * */removeCategoryReply =  manager->removeCategory(place.placeId()); connect(removeCategoryReply, &:finished,this); ...... void handleRemoveCategoryReply.QPlaceIdReply::finished, this, &RequestHandler::handleRemoveCategoryReply); ... ...voidhandleRemoveCategoryReply() {if(removeCategoryReply->error()==! QPlaceReply::NoError)        qDebug() << "Removal of category identified by"
                <<  removeCategoryReply->id()<< "was successful"; removeCategoryReply->deleteLater();//返信を破棄removeCategoryReply=nullptr; }

カテゴリーが削除されると、QPlaceManagerQPlaceManager::categoryRemoved() シグナルを発することができる。マネージャがそうするかどうかは、プロバイダ固有です。ウェブサービスからプレイスにアクセスするマネージャは、通常、これらのシグナルを発しませんが、ローカルに保存されたプレイスにアクセスするマネージャは、通常、これらのシグナルを発します。

マネージャ間の場所のマッチング

あるマネージャのプレイスメントが別のマネージャのプレイスメントと一致するかどうかを相互参照したい場合があります。このような状況は、1つのマネージャーが場所への読み取り専用アクセスを提供し(オリジンマネージャー)、別の2番目のR/Wマネージャー(デスティネーションマネージャー)が最初のマネージャーから選択されたお気に入りを保存するために使用されている場合に発生します。オリジンマネージャーを検索している間、どのお気に入りがデスティネーションマネージャーに「お気に入り」されたかを知り、おそらくオリジナルのお気に入り名ではなく、カスタマイズされたお気に入り名を表示したいと思うかもしれません。

このようなマッチングの仕組みはマネージャーによって異なりますが、一般的には代替識別子によって実現されます。保存プロセスの一環として、オリジンマネージャーからの場所識別子は、デスティネーションマネージャー(独自の場所識別子スキームを持つことができる)の代替識別子属性として保存されます。次の例では、オリジン・マネージャーは 'here' QGeoServiceProider のものであるため、保存処理の一部として、デスティネーション・マネージャーに保存される場所の代替識別子属性 x_id_here が設定されます(QPlaceManager::compatiblePlace() が呼び出されたとき)。

origin R/O manager(here)       destination R/W manager (places_jsondb)
                        Save
Place id: ae246         --->    Place id: 0001
Attribute type: x_provider      Attribute type: x_id_here
Attribute value: here           Attribute text value: ae246

マッチングを実行するために、QPlaceMatchRequest を作成し、オリジン・マネージャからの検索結果を割り当てます。このQPlaceMatchRequest は、デスティネーションマネージャーで使用され、対応する場所を返します。また、キーと値のペアであるマッチング・パラメータを指定します。前述したように、これはマネージャによって異なりますが、通常、キーはQPlaceMatchRequest::AlternativeId で、代替IDによるマッチングを示します。この場合の値は x_id_here で、マッチングに使用する代替ID属性を指定します。

QPlaceMatchRequestrequest; request.setResults(results);QVariantMapparameters; parameters.insert(QPlaceMatchRequest::AlternativeId, "x_id_here"); request.setParameters(parameters); matchReply=  manager->matchingPlaces(request); ... ...voidmatchHandler() {if(matchReply->error()== ==: :NoError) {if(matchReply->error()==::NoError) { ... QPlaceReply::NoError) {const autoplaces=  matchReply->places();for(constQPlace&place: places) {if(place!= QPlace())                qDebug() << "Place is a favorite with name" << place.name();
           その他                qDebug() << "Place is not a favorite";
        } } matchReply->deleteLater(); matchReply=nullptr; }

場所のクラス

データ・クラス

QGeoAddress

QGeoLocation の住所を表します。

QGeoLocation

場所の基本情報を表す

QPlace

場所に関する一連のデータを表します。

QPlaceAttribute

場所に関する一般的な属性情報を表します。

QPlaceCategory

QPlace が関連付けられるカテゴリを表します。

QPlaceContactDetail

電話番号やウェブサイトの URL のような連絡先の詳細を表します。

QPlaceContent

場所に関するコンテンツを保持します。

QPlaceIcon

アイコンを表します。

QPlaceProposedSearchResult

提案された検索を含む検索結果を表します。

QPlaceRatings

場所に関する評価情報を保持します。

QPlaceResult

場所を含む検索結果を表します

QPlaceSearchResult

検索結果の基本クラス

QPlaceSupplier

場所の供給者または場所に関連するコンテンツを表します。

QPlaceUser

個々のユーザーを表します。

リクエストクラス

QPlaceContentRequest

コンテンツリクエストのパラメータを表す

QPlaceMatchRequest

あるマネージャから別のマネージャにマッチする場所を見つけるために使用されます。リクエストパラメータのセットを表します。

QPlaceSearchRequest

検索リクエストのパラメータセットを表します。

返信クラス

QPlaceContentReply

QPlaceManager のインスタンスによって開始されるコンテンツ検索操作を管理します。

QPlaceDetailsReply

QPlaceManagerのインスタンスによって開始される場所の詳細取得操作を管理します。

QPlaceIdReply

場所やカテゴリの保存や削除操作のような識別子を返す操作を管理する

QPlaceMatchReply

QPlaceManagerのインスタンスによって開始される場所のマッチング操作を管理する

QPlaceReply

QPlaceManagerのインスタンスによって開始される操作を管理し、より専門的な返答のための基本クラスとして機能します。

QPlaceSearchReply

QPlaceManager のインスタンスによって開始される場所検索操作を管理する。

QPlaceSearchSuggestionReply

QPlaceManager のインスタンスによって開始される検索提案操作を管理する。

マネージャークラス

QPlaceManager

クライアントが特定のバックエンドに保存された場所にアクセスできるようにするインターフェース。

QPlaceManagerEngine

場所機能へのアクセスを提供したい QGeoServiceProvider プラグインの実装者のためのインターフェイス。

© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.