Difference between revisions of "CELayoutEditor Manual"

Revision as of 11:10, 22 August 2009

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.

The INI file

An important (and sometimes confusing) part of the layout editor is its use of an INI file. This file tells the editor where it can find CEGUI's resource files, such as Imagery and Fonts. These paths are 'forwarded' to CEGUI's internal Resource provider. For example 'CEGUI::DefaultResourceProvider::setResourceGroupDirectory("schemes", <ini_schemes_path>);'.

The paths in this file are the 'base' directory when the editor loads something. It will only append the filename of the loaded Layout or such. So when the user opens the file 'MessageBox.layout', the editor (well, Cegui actually) will complete this to '<ini_layout_path/MessageBox.layout' internally.

The INI file gets created on launch when the editor cannot find it, in which case it will prompt you with this dialog: Select Resources Dialog

From there, you should browse to the root CEGUI datafiles folder. The name 'datafiles' is not required, so you may use 'mygame/media/gui' or something. However the subfolders are defaulted to "fonts", "schemes" and such, just like CEGUI's default 'datafiles'. When pressing 'ok', the values will be stored to the INI file. If you are using a different naming convention, or even a different hierarchy, browse and 'ok' on your root directory at least, and close the editor when it has launched completely. Then it has at least created a file for you to edit more easily.

0.6.x Note: unlike the 0.5 versions, it was decided to ship th 0.6.x installers with default files (the ones used in the CEGUI samples) again, to have at least something to start playing with.

Launched

When the editor has completely launched, meaning that it has found or created the necessary INI file, you will see either a blank sceen, of the last saved layout. This shows the empty version: Empty Main Frame

Starting a new Layout

Before dryly explaining all options, let's actually do something first. You can start a new layout by pressing the New button from the toolbar or File->New from the menu. Either way, the editor will ask you whether or not you would like a 'root' window. If you choose to do so, your layout will start with a full-sized 'DefaultGUISheet' window type. This option is good for a desktop-like setup on which you are going to put your widgets. If you choose 'no', then the editor will not add any window until you explicitely do so. In that case, this first window will become the root. This option is advised if you are splitting your GUI into multiple files. So, it pretty much depends on how you choose to setup your GUI: 'composed' or 'split up'.

As soon as you have started a layout, the Main Dialog image awakes...

The main dialog

This dialog provides a hierachical overview of the currently open layout (the browse tree), allowing for modifying properties of the current selection and adding new windows. It looks as follows: TODO: insert new image

Although the dialog is a "top-most" window, it can be minimized & restored. Also, its visibility can be toggled through 'View->Toggle dialog'.

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 comumn shows the property's name, and the right one its current value.

Adding windows

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

TODO: insert new image

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.

The edit area

Selecting and Moving

Now that you know how to add windows to your layout and fine-tune its properties, let's discuss the edit area. This is the place where you can select, resize, move, copy|cut & paste parts of your layout. Of course, moving or resizing a window is the same as adjusting those position properties in the main dialog. To select more then one window at a time, hold CTRL while clicking.

If a window is selected, it will be wrapped with a resize box: Widget Resize Box

When copying, cutting or pasting parts of a layout, the editor will implicitely use the entire branch (children). To clarify this implication, the 'View->Select All' option will only show a resize box around the top-most windows, and leave the children with a non-resizable box: Selected All Widgets

Two operations (who have no menu item) 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 Menu

When a layout is being edited, these menu contains the following sub-menus and items:

• Edit: This menuitem contains all subitems which are relevant to a Selection of windows. Their behavior should be implied by the item's names and the detailed explaination in the status bar.

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

The status bar

While working in the edit area, the status bar is used to show the following information:

• Absolute and relative coordinates of the currently hovered window (includes the root GUISheet);
• The name of the currently hovered window (includes the root GUISheet);

Saving and Loading layouts

As mentioned in the 'Setup' chapter, the editor uses CEGUI's internal resource loading behaviour. This is also the case for layouts itself. Therefore, when you open a Layout, you are limited to the files which reside in the layoutpath vale of the INI file. So instead of an open-file dialog, the editor will prompt you with a list of all layouts (.xml or .layout) in that directory.

Even though a saved layout can only be opened when saved to the layoutpath directory of your INI file, for convenience reasons you may save it to any location.

More

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: Default Font Dialog

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.

Snap to grid

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

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

Besides the Cegui resource paths, the editor loads & writes several additional 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, August 22, 2009.