Difference between revisions of "CELayoutEditor Manual"

Revision as of 19:37, 14 June 2006

Introduction

Welcome to the manual page for the layout editor! Because the application is not the biggest in the world, this manual is actually pretty brief. However it will explain everything it can do, and will give some notes on certain behaviour which might be confusing at first sight.

Before going any further, make sure you have read Getting Started.

Overview

0.5 Note: this version is not shipped with datafiles anymore. Therefore the editor will prompt you with a directory browser on first usage. You can point it to your datafiles folder, for example the one in cegui's own sample folder. When pressing 'ok', the value will be stored to the INI file.

When you start the editor for the first time, you will obviously see the following screen. The first time it will startup with the sample layout. After that it will start with the most recently opened layout.

View application screenshot

The image shows the following items:

The menu

The menu contains the following sub-menus and items:

• File: This common menuitem contains all document related options, like "new", "open", "save(as)", "close" and completely quitting the application. Each of these

commands will result in the application prompting you to save any modifications first.

• Edit: This menuitem contains all items which are relevant to a <link!>selection of windows</link>. Their behavior should be implied by the item's names

and the detailed explaination in the status bar.

• View: This menuitem contains some convenience commands to grow or shrink the client to commonly-used resolutions such as 1024x768, to help the WYSIWYG behavior. Besides, it allows for aligning and grid setup.

• Help: This menuitem contains an about box and a reference to the page you are now reading :-)

The edit area

This pane allows you to select one or more windows and perform all kinds of operations on them. These include, moving, resizing and all operations in the "edit" menu. To select a window, just left-click it. To select more then one window at a time, hold SHIFT while clicking.

Two operations which are not menuitems have to do with moving windows by hand in stead of by mouse. When you have a selection of windows, you can use 'w', 's', 'a', 'd' and the cursor keys to move the selection. To make smaller steps (1 pixel instead of 10 pixels) keep CTRL pressed.

Note that if you select a first window of a selection, the main dialog (see below) updates.

The status bar

The status bar is used to show the following information:

• Details about the behavior of a highlighted menu item (when you browse the menu);
• Absolute and relative coordinates of the currently hovered window (includes the root GUISheet);
• The name of the currently hovered window (includes the root GUISheet);

The main dialog

This dialog is always open and cannot be closed ;-)

Its tasks include providing a hierachical overview of the currently open layout (the browse tree), allowing for modifying properties of the current selection and adding new windows.

By clicking an item (window name) in the browse tree, that window gets automatically selected, and the dialog updates itself according to the selected window.

Except for the "Text" property, which is shown as an edit field, each (supported) property is editable through a grid, where the left comlumn shows the properties' name, and the right one it's current value.

Common Usage

Adding windows

You can add windows by clicking the "add window" button, which will open the following dialog:

View dialog screenshot

The top of the dialog shows you to which window (the parent) you will be adding the new window. Below that information is an input field for the new window's name.

Since the editor support multiple "look & feels" you can select one of the loaded ones here. As you can see, you can default the one you use most often. Finally, select the window type you'd like to add. This list is relative to the selected look & feel, so it might differ per selection.

When you´re happy with your new window, press `ok` to create with the given settings. Note that the application will fail to add the window if you choose an already existing name.

Editing properties

When you have more then one window selected, the grid will show the union of available properties. Imagine that two windows are selected ( by pressing SHIFT while selecting), and the first one has "visible" and "topMost" as its properties, and the second one has "visible", "clickable" and "colour" as its properties, then the grid will contain "visible", "topmost", clickable" and "colour". "Visible" will only be added once.

Note that the positions and size cannot be changed when you have selected more then one window, otherwise each window in your selection would get the same position and size!

Renaming a window

You can change a window name by modifying the first property ('name') in the grid. Although this property does not actually exist in the cegui system, editing this way helps consistency with changing others property. Name changes will immediately reflect in the tree.

Setting a default font

You can specify a default font for your layout(s). This font will be used for each added window from that moment. When selection "View->Set default font...", you'll see this dialog:

View dialog screenshot

On "ok" this font will apply even after closing the editor, because it's an INI setting.

Working on a background

In order to extend the "wysiwyg" effect, you can set a background behind your layout. This can help alot in deciding how large your widgets can be, or even their ideal location. Note that the background does not get saved with your layout; the editor maintains is seperately. To create a background in your layout itself, you should just use a StaticImage widget.

Setting a background, and toggling its visibility state happens via the "View->Set background" and "View->Show background" menu items respectivily.

Advanced Usage

Snap to grid

It's possible to show a grid during editing. When selection "View->Setup grid...", you'll see this dialog:

View dialog screenshot

On "ok", all settings will apply, even after closing the editor because it's INI settings.

When editing, you can snap to the grid by selecting one or more windows, and press "g" (for "grid", because "s" is already used for moving).

Absolute metrics mode

Although CEGUI does not distinguish between "relative" and "absolute" anymore, you can still simutate this with help of the editor. If you want a window of a fixed size at any resolution (absolute), you can set all the 'scales' to 0.0, and the 'offsets' to an absolute position. For example to create a window from 50,50 to 250,250 at any resolution, the property grid of that window should look like this:

• Left Scale: 0
• Left Offset: 50
• Top Scale: 0
• Top Offset: 50
• Right Scale: 0
• Right Offset: 250
• Bottom Scale: 0
• Bottom Offset: 250

Note that the resizing and dragging of windows only affects the relative part. The absolute part (offsets) must always be setup from the grid.

INI Settings

The editor loads & writes several settings from and to an INI file:

• The location of your datafiles
• Last opened layout
• Client size
• Grid setup
• Default font setup
• Current background setup

Conclusion

I think i have mentioned the most important functionality. You should now be able to create the coolest layouts :-) If you think i left something important out, just add it or send me an email at pkooman@gmail.com.

--Last updated by Scriptkid, May 03.