Difference between revisions of "CELayoutEditor Manual"

From CEGUI Wiki - Crazy Eddie's GUI System (Open Source)
Jump to: navigation, search
(→‎Using the editor)
m (→‎Adding windows)
 
(39 intermediate revisions by 5 users not shown)
Line 1: Line 1:
−
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
+
== Introduction ==
−
will explain everything it can do, and will give some notes on certain behavior which might be confusing at firs sight.
+
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]].
+
Before going any further, make sure you have read [[CELayout Editor - Getting Started / Building]].
  
−
===Using the editor===
+
== 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>);'.
  
−
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. Below the screen i will explain the marked spots.
+
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.
  
−
[http://www.2dgame-tutorial.com/downloads/StartupImage.PNG View application screenshot]
+
The INI file gets created on launch when the editor cannot find it, in which case it will prompt you with this dialog:
 +
[http://www.cegui.org.uk/gallery/displayimage.php?pid=29&fullsize=1 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.
  
−
'''1. The menu'''
+
'''Vista note:''' Since applications are not allowed to write files in the application directory itself, it uses a 'Virtual Store' for backwards compatibility. [http://www.cegui.org.uk/phpBB2/viewtopic.php?f=7&t=3439 This thread] explains the details. It also contains a post of myself saying that i should update the editor to use the application directory, which is nicer anyway.
  
−
The menu contains the following sub-menus and items:
+
'''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.
  
−
''File'' - This common menuitem contains all document related options, like "new", "open", "save(as)", "close" and complete quiting the application. Each of these
+
== Launched ==
−
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
+
When the editor has completely launched, meaning that it has found or created the necessary INI file, you will see either a blank sceen or the last saved layout. This shows the empty version:
−
and the detailed explaination in the status bar.
+
[http://www.cegui.org.uk/gallery/displayimage.php?pid=28&fullsize=1 Empty Main Frame]
  
−
''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.
+
=== Starting a new Layout ===
  
−
''Help'' - This menuitem contains an about box and a reference to the page you are now reading :-)
+
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...
  
−
'''2. The edit area'''
+
=== The main dialog ===
  
−
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.
+
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:
−
To select a window, just left-click it. To select more then one window at a time, hold SHIFT while clicking.
+
'''TODO: insert new image'''
  
−
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
+
Although the dialog is a "top-most" window, it can be minimized & restored. Also, its visibility can be toggled through 'View->Toggle dialog'.
−
'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.
+
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.
  
−
'''3. The status bar'''
+
=== Adding windows ===
 +
You can add windows by clicking the "add window" button, which will open the following dialog:
  
−
The status bar is used to show the following information:
+
'''TODO: insert new image'''
−
*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);
+
  
 +
Image of Mac Version: [https://picasaweb.google.com/lh/photo/zLHy_P9Us5lFxiehidN2BtMTjNZETYmyPJy0liipFm0?feat=directlink]
  
−
'''4. The main dialog'''
+
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.
  
−
This dialog is always open and cannot be closed ;-)
+
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.
  
−
Its tasks include providing a hierachical overview of the currently open layout (the browse tree), allowing for modifying properties of the current
+
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.
−
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.
+
=== 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.
  
−
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.
+
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.
  
−
'''Adding windows'''
+
== The edit area ==
  
−
You can add windows by clicking the "add window" button, which will open the following dialog:
+
=== Selecting and Moving ===
  
−
[http://www.2dgame-tutorial.com/downloads/AddWindowDialog.PNG View dialog screenshot]
+
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.
  
−
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
+
If a window is selected, it will be wrapped with a resize box:
−
name.
+
[http://www.cegui.org.uk/gallery/displayimage.php?pid=34&fullsize=1 Widget Resize Box]
  
−
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,
+
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:
−
select the window type you'd like to add. This list is relative to the selected look & feel, so it might differ per selection.
+
[http://www.cegui.org.uk/gallery/displayimage.php?pid=33&fullsize=1 Selected All Widgets]
  
−
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.
+
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 ===
  
−
'''Editing properties'''
+
When a layout is being edited, these menu contains the following sub-menus and items:
  
−
When you have more then one window selected, the grid will show the union of available properties. Imagine that two windows are selected (
+
* 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.
−
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". Note that "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!
+
* 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 ===
  
−
'''Setting a default font'''
+
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);
  
−
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:
+
== 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:
 +
[http://www.cegui.org.uk/gallery/displayimage.php?pid=32&fullsize=1 Select Layout dialog]
  
−
[http://www.2dgame-tutorial.com/downloads/DefaultFontDialog.PNG View dialog screenshot]
+
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.
  
−
On "ok", this font will apply, even after closing the editor because it's an INI setting.
+
== 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: [http://www.cegui.org.uk/gallery/displayimage.php?pid=31&fullsize=1 Default Font Dialog]
  
−
'''Setting up the grid (Note: CVS only yet!)'''
+
On "ok" this font will apply even after closing the editor, because it's an INI setting.
  
−
It's possible to show a grid during editing. When selection "View->Setup grid...", you'll see this dialog:
+
=== 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.
  
−
[http://www.2dgame-tutorial.com/downloads/GridDialog.PNG View dialog screenshot]
+
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:
 +
[http://www.cegui.org.uk/gallery/displayimage.php?pid=30&fullsize=1 Snap to grid Dialog]
  
 
On "ok", all settings will apply, even after closing the editor because it's INI settings.
 
On "ok", all settings will apply, even after closing the editor because it's INI settings.
Line 101: Line 117:
 
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).
 
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).
  
−
===Conclusion===
+
=== 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.
  
−
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 scriptkid@2dgame-tutorial.com.
+
--Last updated by Scriptkid, August 22, 2009.
  
−
--Last updated by Scriptkid, November 18.
+
[[Category:CELayoutEditor]]

Latest revision as of 23:43, 16 December 2011

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 CELayout Editor - Getting Started / Building.

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.

Vista note: Since applications are not allowed to write files in the application directory itself, it uses a 'Virtual Store' for backwards compatibility. This thread explains the details. It also contains a post of myself saying that i should update the editor to use the application directory, which is nicer anyway.

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 or 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

Image of Mac Version: [1]

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: Select Layout dialog

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.

Retrieved from "http://cegui.org/wiki/index.php?title=CELayoutEditor_Manual&oldid=4691"