A number of objects like buttons, edit-boxes, containers, etc. may have a
text label. This label may primarly contain the text to be shown on the
surface of the object in a manner that is useful (e.g. the edit-box will
put it to the left of the input field, but the container will put it at
top as a header).
The label must not necessarily be static or constant memory, the object
will make a copy of the text.
Labelled objects will adapt thier size to the size of the text.
The label may be extended with
additional information.
- A '~' (tilde) before a letter will make that one to a hot-key.
- A '_' will make a new line (currently only implemented for buttons
and icons). The '_' itself will not be displayed.
- A control character (ascii code < 32). The binary value will be used
as hot-key. This may be useful for attatching hot-keys like
or to the object.
- A '#' followed by a numeric value and terminating with ';'
like "#130;", which will assign the key with ascii-code 130 (0x82)
to the object.
- A '#' followed by two numeric values separated by a comma and
terminating with ';' like "#82,1;". The first one will be
interpreted as the scan-code, and the second the character code
recieved from Allegro (i.e. a control code for cases of interest).
E.g. "#82,1;" will assign the shift-insert key-press as hot-key for
the object.
- Some objects may also contain the "#name;" command. This means that
an image with the name `name' shall be used to display the object.
The image may be combined with a text. The image must have been
previously loaded by the CGUI-function `CguiLoadImage'. Objects that
currently recognises images are Buttons, Icons and general
menu-items (not radio or check-items).
- The text string to `Req' has a special format with a leading
info-text followed by a sequence of at least one button-label,
all within the same string. The button-labels are indicated by a
leading '|'.
If you need to actually draw any of the above control-characters - just
type them twice in the string.
See also:
AddButton,
MkMenuItem,
AddIcon,
Req.
int CguiLoadImage(const char *filename, const char *imagename, int type, int id);
This function loads an image with name `imagename' from file `filename'.
Why? - The image as well as its name will be registered in the CGUI
system which means:
- You may later refer to that image when creating
objects, i.e. you can use the `imagename' in the label string to
specify that it shall be the icon used for the object.
- When node `id' is destroyed the image will also be - you
don't need to worry about returning the memory.
- If you let the user change the colour depth by use of the dialogue
`ScrMode', the images will be converted to the new pixel format (if
that is possible).
An image associated with a node may be referred from
objects that are put into that node (at any depth). I.e. if `id' is a
window, any object put into that window can use that image, or if `id'
is a container, any object put into that container can use it. Also all
objects of a sub-window can use the images of a parent window.
If you want to make an image `global' (i.e. it will remain in
memory until CGUI is shut down), just pass 0 for `id'.
Loading images from 8-bit colour files to a screen mode of 8-bit colour
will only work properly if all pictures uses one common palette. Loading
8-bit colour files into high colour or true colour modes will work
properly only if transparent colour is not used. The same limitation
applies to the reverse (high -> 8).
In short: to avoid problems use 24-bits files, and at least
15 bit colour-depth on the screen.
Parameters:
- filename: The path/name of the file that contains the image to load.
The file-extension may either be any of the types recognised by
the Allegro function `load_bitmap' or a ".dat".
- imagename: A string that identifies the image. In subsequent
references to the image (e.g. when creating a button that shall
display the image) this name must be used.
In case the file is an Allegro-datafile (detected by the
extension ".dat") the imagename is ignored.
- In case of loading a single image from a DATA-file
the name ending the path will be used as image name (you have to
use that one as when referencing the image).
- Multiple images can be loaded with a single call, provided that
they are stored within a datafile at the same nesting level. If
`filename' is e.g. "my_icons.dat" then all images at the
top-level of "my_icons.dat" will be loaded, and the image
names to use is the names of the objects in the data file. If
`filename' is e.g. "my_data.dat#icons/the_dialog" and
"the_dialog" is a data-file object of type `DAT_FILE' then all
images in that data-file ("directory") will be loaded. The
meaning of "images" is in this case bitmaps, compiled sprites
and rle sprites.
- type: This parameter controls if CGUI shall draw a bitmap in
transparent mode (draw_sprite) or in solid mode (blit). In case the
image is loded from a datafile and the type of the object is
COMPILED_SPRITE or RLE_SPRITE the type parameter will be ignored.
Image type macros:
- IMAGE_BMP: bmp will be handled as a non transparent bitmap.
- IMAGE_TRANS_BMP: bmp will be handled as a transparent bitmap.
- id: The id-key from the node which to hook the image onto. This
means that when node `id' is destroyed (e.g. because a window is
be closed) also the image will be destroyed. Typically `id' is the
id-key of a window. If you want to keep an image during the lifetime
of the program, just pass 0 for id. If the passed `id' refers to a
simple object rather than a container or window, the image will be
hooked into the parent of `id' instead.
Return value: The id of the node where the image is stored if
sucessful othewise -1.
See also:
RegisterImage,
ScrMode,
GetRegisteredImage.
int RegisterImage(void *data, const char *imagename, int type, int id);
Works analogous to `CguiLoadImage' but registers an image that is already
in memory. `RegisterImage' will not make a copy of `bmp' so it must not
be freed or reallocated as long as it is in use (i.e. as long as object
id is not destroyed).
In contrary to images loaded from file the registered ones
will not be automaticallay adjusted when CGUI dialogue for changeing
the screen settings are used.
The `type' parameter shall be either of the IMAGE_* values
meaning:
- IMAGE_BMP: bmp will be handled as a non transparent bitmap.
- IMAGE_TRANS_BMP: bmp will be handled as a transparent bitmap.
- IMAGE_RLE_SPRITE: a RLE_SPRITE will be created from bmp
- IMAGE_CMP_SPRITE: a COMPILED_SPRITE will be created from bmp
Call `RegisterImage' with NULL for `data' if you want to unregister a
previously registered image (the name is your handle). You can also
replace a previous registration by subsequent calls to `RegisterImage'
using the same name. This can be used to make simple animations on
objects (which includes plain image objects like those made by `AddTag'),
see also the examples.
Return value: 0 if it failed (i.e. unknown type, unknown id), else 1.
See also:
CguiLoadImage,
GetRegisteredImage.
Returns a pointer to an image with name `imagename' in node `id' that
has previously been registered by `RegisterImage' or `CguiLoadImage'. The
integer pointed to by `type' will be set to the type of the image, see
IMAGE_* macros. The type of the returned pointer corresponds to the
type value.
See also:
RegisterImage,
CguiLoadImage.
Back to contents