QGraphicsItem Class

Detailed Description

QGraphicsItemクラスは、QGraphicsScene内のすべてのグラフィックアイテムの基本クラスです。

独自のカスタムアイテムを作成するための軽量な基盤を提供します。 これには、アイテムのジオメトリ、衝突の検出、そのペイントの実装、イベントハンドラによるアイテムの相互作用の定義が含まれます。 QGraphicsItemは、グラフィックスビューフレームワークの一部です。

利便性のために、Qtは最も一般的な図形のための標準グラフィックス項目のセットを提供します。 これらは：

-QGraphicsEllipseItemは楕円アイテムを提供します
-QGraphicsLineItemは広告申込情報を提供します
-QGraphicsPathItemは任意のパス項目を提供します
-QGraphicsPixmapItemはピックスマップアイテムを提供します
-QGraphicsPolygonItemはポリゴンアイテムを提供します
-QGraphicsRectItemは長方形のアイテムを提供します
-QGraphicsSimpleTextItemは簡単なテキストラベルアイテムを提供します
-QGraphicsTextItemは、高度なテキストブラウザ項目を提供します。

アイテムのすべての幾何情報は、ローカル座標系に基づいています。 アイテムの位置pos()は、親座標の位置を返すため、ローカル座標では動作しない唯一の関数です。 グラフィックスビュー座標系は、座標系を詳細に記述します。

setVisible()を呼び出すことでアイテムを表示する（つまり、描画し、イベントを受け入れる）かどうかを設定できます。 アイテムを非表示にすると、その子も非表示になります。 同様に、setEnabled()を呼び出して項目を有効または無効にすることができます。 アイテムを無効にすると、そのすべての子も無効になります。 デフォルトでは、項目は表示され有効になっています。 項目が選択されているかどうかを切り替えるには、まずItemIsSelectableフラグを設定して選択を有効にしてから、setSelected()を呼び出します。 通常、選択はユーザの操作の結果としてシーンによって切り替えられます。

独自のグラフィックアイテムを作成するには、最初にQGraphicsItemのサブクラスを作成し、次に2つの純粋な仮想パブリック関数を実装することから始めます：boundingRect()：アイテムによって描画された領域の見積もりを返します。paint() 実際の絵画 例えば：

class SimpleItem : public QGraphicsItem
{
public:
    QRectF boundingRect() const
    {
        qreal penWidth = 1;
        return QRectF(-10 - penWidth / 2, -10 - penWidth / 2,
                      20 + penWidth, 20 + penWidth);
    }

    void paint(QPainter *painter, const QStyleOptionGraphicsItem *option,
               QWidget *widget)
    {
        painter->drawRoundedRect(-10, -10, 20, 20, 5, 5);
    }
};

boundingRect()関数にはさまざまな目的があります。 QGraphicsSceneはその項目インデックスをboundingRect()に基づいており、QGraphicsViewは不可視項目の間引きと、重複項目を描画するときに再構成が必要な領域の決定の両方に使用します。 さらに、QGraphicsItemの衝突検出メカニズムは、効率的なカットオフを提供するためにboundingRect()を使用します。 collidesWithItem()の細粒度の衝突アルゴリズムは、QPainterPathとしてアイテムの形状の正確なアウトラインを返すshape()を呼び出すことに基づいています。

QGraphicsSceneは、すべての項目boundingRect()およびshape()が通知されない限り、変更されないままであることを期待しています。 アイテムのジオメトリを変更するには、prepareGeometryChange()を呼び出してQGraphicsSceneがその簿記を更新できるようにする必要があります。

衝突検出は2つの方法で行うことができます。

1.あなたのアイテムの正確な形状を返すためにshape()を再実装し、collidesWithItem()のデフォルトの実装に依存してシェイプシェイプの交差を行います。 形状が複雑な場合は、かなり高価になる可能性があります。
2.collidesWithItem()を再実装して独自のカスタムアイテムとシェイプの衝突アルゴリズムを提供します。
contains()関数を呼び出して、項目にポイントが含まれているかどうかを判断できます。 この関数は、アイテムによって再実装することもできます。 contains()のデフォルトの動作は、shape()を呼び出すことに基づいています。

アイテムは他のアイテムを含むことができ、他のアイテムにも含まれます。 すべてのアイテムは、親アイテムと子リストを持つことができます。 アイテムに親がない場合を除き、その位置は親座標（親のローカル座標）になります。 親アイテムは、その位置とその変換をすべての子に伝播します。

Transformations

QGraphicsItemは、ベース位置pos()に加えて射影変換をサポートします。アイテムの変換を変更する方法はいくつかあります。単純な変換では、便利な関数setRotation()またはsetScale()を呼び出すか、任意の変換行列をsetTransform()に渡すことができます。高度な変換コントロールの場合、setTransformations()を呼び出すことによって複数の結合された変換を設定するオプションもあります。

アイテムの変換は親から子へと累積されるため、親アイテムと子アイテムの両方が90度回転すると、子の合計変換は180度になります。同様に、アイテムの親が元のサイズの2倍にスケールされている場合、その子も2倍の大きさになります。アイテムの変換は、ローカルジオメトリには影響しません。すべてのジオメトリ関数（contains()、update()、すべてのマッピング関数など）は、依然としてローカル座標で動作します。便宜上、QGraphicsItemは、アイテムの総変換行列（その位置とすべての親の位置と変換を含む）を返す関数sceneTransform()と、シーン座標の位置を返すscenePos()を提供します。アイテムのマトリックスをリセットするには、resetTransform()を呼び出します。

特定の変換操作は、適用される順序に応じて異なる結果を生成します。たとえば、変換をスケールしてから回転すると、変換が最初に回転した場合とは異なる結果になることがあります。ただし、QGraphicsItemで変換プロパティを設定しても、結果の変換には影響しません。 QGraphicsItemは常に固定の定義された順序でプロパティを適用します。

アイテムのベーストランスフォームが適用されます（transform()）。
アイテムの変換リストが順番に適用されます（変換()）
アイテムは、変換元点（rotation()、transformOriginPoint()）に対して相対的に回転します。
アイテムは、変換元点（scale()、transformOriginPoint()）に対して相対的にスケーリングされます。

Painting

paint()関数はQGraphicsViewによって呼び出され、アイテムの内容をペイントします。 アイテムには背景やデフォルトの塗りつぶしがありません。 アイテムの背後にあるものは、この機能で明示的に塗装されていないすべての領域を照らします。 update()を呼び出すと、再描画をスケジュールできます。必要に応じて、再描画が必要な四角形を渡すこともできます。 アイテムがビューに表示されるかどうかによって、アイテムは再描画される場合とされない場合があります。 QGraphicsItemにはQWidget::repaint()と同等の機能はありません。

アイテムは、親アイテムから始まって子を描画するビューを、昇順にスタック順に描画します。 setZValue()を呼び出してアイテムの積み重ね順序を設定し、z値の高いアイテムの前に塗りつぶされたz値のアイテムをzValue()を呼び出してテストできます。 積み重ね順序は兄弟アイテムに適用されます。 両親は常に子供の前に描かれています。

Sorting

すべてのアイテムは定義された安定した順序で描画され、この同じ順序で、シーンをクリックするとマウス入力を最初に受け取るアイテムが決まります。 通常は、シーンの論理構造に従って、項目が「自然順番」に従うので、並べ替えについて心配する必要はありません。

アイテムの子は親の上に積み重ねられ、兄弟アイテムは挿入順に（つまり、シーンに追加された、または同じ親に追加されたのと同じ順序で）積み重ねられます。 アイテムAとBを追加すると、BがAの上に表示されます。次にCを追加すると、アイテムの積み上げ順序はA、B、Cの順になります。

この例では、ドラッグアンドドロップロボットの例によるロボットのすべての肢の積み重ね順序を示しています。 胴体はルートアイテムです（他のすべてのアイテムは胴体の子または子孫です）ので、最初に描画されます。 次に、胴の子供のリストの最初の項目であるため、頭が描画されます。 次に左上の腕が引かれます。 下腕は上腕の子であるため、下腕を引き、上腕の次の兄弟が上になるなどの順番で描かれます。

上級ユーザーの場合、アイテムのソート方法を変更する方法があります。

アイテムに対してsetZValue()を呼び出すと、他の兄弟アイテムの上または下に明示的にスタックすることができます。 アイテムのデフォルトZ値は0です。同じZ値を持つアイテムは、挿入順にスタックされます。
stackBefore()を呼び出して、子のリストを並べ替えることができます。 これにより、挿入順序が直接変更されます。
ItemStacksBehindParentフラグを設定すると、子アイテムを親の背後にスタックすることができます。
2つの兄弟アイテムの積み重ね順は、各アイテムの子アイテムと子孫アイテムもカウントします。 したがって、1つのアイテムが別のアイテムの上にある場合、そのすべての子も他のすべてのアイテムの子の上にも配置されます。

Events

QGraphicsItemは、仮想関数sceneEvent()を介してQGraphicsSceneからイベントを受け取ります。この関数は最も一般的なイベントをコンビニエンスイベントハンドラのセットに配信します。

コンテキストメニューイベントを処理するcontextMenuEvent()
focusInEvent()およびfocusOutEvent()は、フォーカスイン/アウトイベントを処理します。
hoverEnterEvent()、hoverMoveEvent()、およびhoverLeaveEvent()は、ホバーの入力、移動および離脱を処理します
inputMethodEvent()は、アクセシビリティサポートのために入力イベントを処理します。
keyPressEvent()およびkeyReleaseEvent()は、キーの押下および解放イベントを処理します。
mousePressEvent()、mouseMoveEvent()、mouseReleaseEvent()、およびmouseDoubleClickEvent()は、マウスの押下、移動、解放、クリック、およびダブルクリックのイベントを処理します。
イベントフィルタをインストールすることにより、他の項目のイベントをフィルタリングできます。この機能は、QObjectのサブクラスでのみ機能するQtの通常のイベントフィルタ（QObject::installEventFilter()を参照）とは別です。項目をinstallSceneEventFilter()を呼び出して別の項目のイベントフィルタとしてインストールした後、フィルタ処理されたイベントは仮想関数sceneEventFilter()によって受信されます。アイテムイベントフィルタは、removeSceneEventFilter()を呼び出して削除できます。

Custom Data

カスタムデータを標準アイテムに登録すると便利な場合があります。 キーと値のペア（キーは整数、値はQVariant）を使用して、データを格納するアイテムに対してsetData()を呼び出すことができます。 アイテムからカスタムデータを取得するには、data()を呼び出します。 この機能はQt自体に全く影響されません。 ユーザの利便性のために提供される。

QGraphicsScene、QGraphicsView、およびGraphics View Frameworkも参照してください。

Member Type Documentation

enum QGraphicsItem::CacheMode

この列挙型は、QGraphicsItemのキャッシュモードを記述します。 キャッシングは、アイテムを再描画する必要があるときに再利用できるオフスクリーンピクセルバッファに割り当ててレンダリングすることによってレンダリングを高速化するために使用されます。 いくつかのペイントデバイスでは、キャッシュはグラフィックメモリに直接格納されているため、レンダリングが非常に迅速になります。

この列挙型は、Qt4.4で導入または変更されました。

QGraphicsItem::setCacheMode()も参照してください。

enum QGraphicsItem::GraphicsItemChange

この列挙型は、QGraphicsItem::itemChange()によって通知される状態の変化を記述します。 状態が変わると通知が送信され、場合によっては調整が行われます（詳細については、各変更のドキュメントを参照してください）。

注：QGraphicsItem自体のitemChange()内で関数を呼び出すと、特定の関数呼び出しによって不要な再帰が発生する可能性があるので注意してください。 たとえば、ItemPositionChange通知のitemChange()でsetPos()を呼び出すことはできません。これは、setPos()関数がitemChange（ItemPositionChange）を再度呼び出すためです。 代わりに、itemChange()から新しい調整された位置を返すことができます。

enum QGraphicsItem::GraphicsItemFlag

flags QGraphicsItem::GraphicsItemFlags

この列挙型では、項目の動作のさまざまな機能を切り替えるために項目に設定できるさまざまなフラグについて説明します。

すべてのフラグは、デフォルトで無効になっています。

注：このフラグはItemContainsChildrenInShapeと似ていますが、さらに子をクリッピングして包含を強制します。

QGraphicsScene Class

Detailed Description

QGraphicsSceneクラスは、多数の2Dグラフィックアイテムを管理するためのサーフェスを提供します。

クラスはQGraphicsItemsのコンテナとして機能します。 これはQGraphicsViewと共に使用され、2Dサーフェス上の線、矩形、テキスト、またはカスタムアイテムなどのグラフィックアイテムを視覚化します。 QGraphicsSceneはGraphics View Frameworkの一部です。

QGraphicsSceneには、アイテムの場所の両方を効率的に決定する機能と、シーンの任意の領域内で表示されるアイテムを決定する機能もあります。 QGraphicsViewウィジェットを使用すると、シーン全体を視覚化したり、シーンの一部だけを拡大して表示したりすることができます。

例：

QGraphicsScene scene;
scene.addText("Hello, world!");

QGraphicsView view(&scene);
view.show();

QGraphicsSceneには独自の外観がないことに注意してください。それはアイテムを管理するだけです。シーンを視覚化するためにQGraphicsViewウィジェットを作成する必要があります。

シーンにアイテムを追加するには、まずQGraphicsSceneオブジェクトを作成します。 addItem()を呼び出して既存のQGraphicsItemオブジェクトを追加するか、addEllipse()、addLine()、addPath()、addPixmap()、addPolygon()、addRect()のいずれかを呼び出すか、 ）、またはaddText()であり、すべて新しく追加された項目へのポインタを返します。これらの機能で追加されたアイテムの寸法は、アイテムの座標系に対するものであり、アイテムの位置はシーン内で（0、0）に初期化されます。

QGraphicsViewを使用してシーンを視覚化することができます。シーンが変化すると（例えば、アイテムが移動したり変形したりすると）、QGraphicsSceneはchanged()信号を送出する。アイテムを削除するには、removeItem()を呼び出します。

QGraphicsSceneは、索引付けアルゴリズムを使用してアイテムの位置を効率的に管理します。デフォルトでは、BSP（Binary Space Partitioning）ツリーが使用されます。大部分のアイテムが静的なままである（すなわち、動き回らない）大きなシーンに適したアルゴリズム。このインデックスを無効にするには、setItemIndexMethod()を呼び出します。使用可能な索引付けアルゴリズムの詳細は、itemIndexMethodプロパティを参照してください。

シーンの境界矩形は、setSceneRect()を呼び出すことによって設定されます。アイテムはシーンの任意の位置に置くことができ、シーンのサイズはデフォルトでは無制限です。シーンrectは、内部簿記のためにのみ使用され、シーンのアイテムインデックスを維持します。シーンrectが設定されていない場合、QGraphicsSceneはitemsBoundingRect()によって返されるすべてのアイテムの境界領域をシーンrectとして使用します。しかし、itemsBoundingRect()は、シーン上の各アイテムの位置情報を収集することによって動作するので、比較的時間がかかる関数です。このため、大きなシーンで操作する場合は常にシーンの矩形を設定する必要があります。

QGraphicsSceneの最大の強みの1つは、アイテムの位置を効率的に決定する能力です。シーン上に何百万ものアイテムがあっても、items()関数は数ミリ秒以内にアイテムの位置を決定することができます。アイテム()にはいくつかのオーバーロードがあります：特定の位置にあるアイテムを見つけるアイテム、ポリゴンや四角形の内側または交差するアイテムを見つけるアイテムなどです。返された項目のリストは、スタックの順序でソートされます。一番上の項目はリストの最初の項目です。便宜上、指定された位置の一番上の項目を返すitemAt()関数もあります。

QGraphicsSceneはシーンの選択情報を保持します。項目を選択するには、setSelectionArea()を呼び出し、現在の選択をクリアするには、clearSelection()を呼び出します。 selectedItems()を呼び出して、選択したすべての項目のリストを取得します。

Event Handling and Propagation

QGraphicsSceneが持つ別の責任は、QGraphicsViewからのイベントを伝播することです。シーンにイベントを送信するには、QEventを継承するイベントを作成し、QApplication::sendEvent()などを使用してイベントを送信します。 event()はイベントを個々のアイテムにディスパッチする役割を担います。いくつかの一般的なイベントは、便利なイベントハンドラによって処理されます。たとえば、キープレスイベントはkeyPressEvent()によって処理され、マウスプレスイベントはmousePressEvent()によって処理されます。

キーイベントはフォーカスアイテムに配信されます。フォーカス項目を設定するには、setFocusItem()を呼び出すか、フォーカスを受け入れる項目を渡すか、項目自体がQGraphicsItem::setFocus()を呼び出すことができます。 focusItem()を呼び出して、現在のフォーカス項目を取得します。ウィジェットとの互換性のために、シーンは独自のフォーカス情報も保持します。デフォルトでは、シーンにはフォーカスがなく、すべてのキーイベントは破棄されます。 setFocus()が呼び出された場合、またはシーンの項目がフォーカスを取得した場合、シーンは自動的にフォーカスを取得します。シーンにフォーカスがある場合、hasFocus()はtrueを返し、キーイベントがある場合はフォーカスアイテムに転送されます。アイテムにフォーカスがある間にシーンがフォーカスを失った場合（すなわち、誰かがclearFocus()を呼び出す場合）、シーンはそのアイテムのフォーカス情報を維持し、シーンがフォーカスを取り戻すと、最後のフォーカスアイテムがフォーカスを回復することを確認する。

マウスオーバーエフェクトの場合、QGraphicsSceneはホバーイベントを送出します。アイテムがホバーイベントを受け入れる場合（QGraphicsItem::acceptHoverEvents()を参照）、マウスがその領域に入るとGraphicsSceneHoverEnterイベントを受け取ります。マウスがアイテムの領域内を移動し続けると、QGraphicsSceneはGraphicsSceneHoverMoveイベントを送信します。マウスがアイテムの領域を離れると、アイテムはGraphicsSceneHoverLeaveイベントを受け取ります。

すべてのマウスイベントは、現在のマウスグラバー項目に配信されます。アイテムがマウスイベントを受け入れた場合、アイテムはシーンのマウスグラバーになり（QGraphicsItem::acceptedMouseButtons()を参照）、マウスを押します。他のマウス・ボタンが押されていないときにマウス・リリースを受け取るまで、マウス・グラバーはそのままです。 mouseGrabberItem()を呼び出して、現在どのアイテムがマウスをつかんでいるかを調べることができます。

QGraphicsItemおよびQGraphicsViewも参照してください。