Introduction

In this tutorial we will outline how Anchoring works, and use it to define how Widget's behave when their parent Widget is resized.

Step 1 : Creating a Window with a Button in it

To show how anchoring is done, we will use a Window with a button in it. The following code will create such a setup:

QuickGUI::Sheet* defaultSheet = mGUIManager->getActiveSheet();
  QuickGUI::Button* myButton = defaultSheet->createWindow(Rect(300,300,200,200))->createButton(QuickGUI::Rect(50,50,100,25),"Click Me!");

Run the application. By default, there should be a Window with a Button, 50 pixels from the top of Window's client area, and 50 pixels from the left of the Window's client area. By default, most widgets have a vertical Anchor of ANCHOR_VERTICAL_TOP, and a default horizontal anchor ANCHOR_HORIZONTAL_LEFT. This means that the Button's position will always remain the same distance from the top and left of its parent. If you resize the window, you will notice the Button always remains 50 pixels from the top and from the left of the client area.

Step 2 : Modifying a Widget's Anchors to achieve relative positioning

Lets see what happens when we set the horizontal anchor to ANCHOR_HORIZONTAL_RIGHT:

myButton->setHorizontalAnchor(QuickGUI::ANCHOR_HORIZONTAL_RIGHT);

Run the app, and resize the window. The right side of the button will always remain the same distance from the right of the Window's client area. If you want to understand the technical details of how anchoring works, you can read the next paragraph, which outlines the exact distance the button will be, from the right side of the Window's client area.

In order to get the distance between the right side of the Window's client area and the right side of the child Button, the Windows client size needs to be known. This requires knowing how wide the Window's borders are. If we assume the left and right border to be 10 pixels wide each, we know the Window's client area will be 300 - 10 - 10, or 280. The button's right edge will be the x position plus the width, or 50 + 100, or 150 pixels from the client area's origin. This means that the Button will always remain 280 - 150, or 130 pixels from the right of the Window's client area.

Now lets change the vertical anchor to ANCHOR_VERTICAL_BOTTOM:

myButton->setVerticalAnchor(QuickGUI::ANCHOR_VERTICAL_BOTTOM);

Run the app, and resize the window. As you would have guessed, the Button's position is relative to the bottom and right side of the window.

Step 3: Using Anchors to achieve a relative size

It is important to know that Anchors use different sides to maintain its relative positioning. ANCHOR_HORIZONTAL_LEFT makes sure that a widget's left side always remains the same distance from its Parent widget's left side. ANCHOR_HORIZONTAL_RIGHT maintains the same distance using the widget's right side. In this way, we can easily implement resizing of widgets, but applying an anchor from the left side, and from the right side. Lets see it in action:

myButton->setHorizontalAnchor(QuickGUI::ANCHOR_HORIZONTAL_LEFT_RIGHT);

Run the app, and resize the window. Both the left and right side should remain the same distance from the Window's client area. In order for the distances to be maintained, the button must grow and shrink, depending on its parent's size. Vertical resizing can be done in a similar manner, using ANCHOR_VERTICAL_TOP_BOTTOM.

Step 4: Maintaining relative position and size of Widgets on the Sheet

It is important to note that a Sheet does not need to be the same size as the viewport it is drawn in, and they are not updated automatically when the viewport size is changed. It is up to the user to notify the GUIManager that the viewport size has changed, and to update the Sheet size, if necessary. By resizing the Sheet, the child widgets will maintain their position and size, according to their anchors. In this way, it is easily possible to have a Sheet that will behave correctly when the viewport size changes, for example if the RenderWindow becomes larger, or the resolution changes. It is also convenient because Users can define widget positions and sizes according to a set Sheet size, and later on modify the Sheet size, knowing the widgets will behave properly.