CRM32Pro_IButton Class Reference

IButton. More...

Detailed Description

IButton.

Button interface system.

Public Member Functions
int	Check (void)
	Return the ID of a clicked button without draw anything. More...
int	Clone (int id)
	Create a clone button from the given Master button ID and put it as a working button on the current layer. More...
int	Create (struct IButtonNew *button, char *tilename, unsigned char master, char *fDPF)
	Add a new button to current layer. More...
int	Create (struct IButtonNew *button, char *tilename, unsigned char master, int idDPF)
	Add new button to current layer. More...
unsigned char	Delete (char *fDPF, char *butname)
	Delete a button from a DPF file. More...
unsigned char	Delete (int idDPF, char *butname)
	Delete a button from an idDPF. More...
int	Draw (void)
	Draw current state's buttons of all visible layers returning the ID of clicked button. More...
void	ForceDraw (void)
	Deprecated. Just present for backward compatibility.
int	GetAlpha (int id, int state)
	Get alpha blending information. More...
int	GetColorKey (int id, int state)
	Get the current color key. More...
int	GetColorSelect (int id)
	Get the color select to the given ID button. More...
int	GetKey (int id)
	Get the assigned key to the given ID button. More...
char	GetLayer (void)
	Get the current working layer. More...
char	GetLayerVisibility (char l)
	Get the visibility of a given layer. More...
int	GetMouseButtons (int id)
	Get current mouse button sensibility of given IButton. More...
char *	GetName (int id)
	Get the name of a given button. More...
int	GetNum (void)
	Get number of working buttons (clones and normal, not master) More...
int	GetRange (int id)
	Get the range of slider or progress. More...
int	GetState (int id)
	Get current state of given ID button. More...
SDL_Surface *	GetSurface (int id, int state)
	Get the surface of the given ID/state button. More...
char *	GetText (int id)
	Get current text. Only works with InputText button. More...
int	GetValue (int id)
	Get current value of slider or progress. More...
int	Info (int m=-1)
	Get useful information. More...
int	Load (char *fDPF, char *butname, unsigned char master=0)
	Load a button from a specified DPF(using a filename) and add it to current layer. More...
int	Load (int idDPF, char *butname, unsigned char master=0)
	Load a button from a specified DPF(using an idDPF) and add it to current layer. More...
unsigned char	LoadHeader (char *fDPF, char *butname, IButtonNew *info)
	Only load the button header from a DPF file. More...
unsigned char	LoadHeader (int idDPF, char *butname, IButtonNew *info)
	Only load the button header from an idDPF. More...
void	Remove (int id)
	Remove a button given its ID. More...
void	RemoveAll (void)
	Remove all buttons of current layer.
void	RemoveMaster (int id)
	Remove a master button given its ID. More...
int	Save (char *fDPF, char *butname, IButtonNew *button)
	Save a button to a DPF file. More...
int	Save (int idDPF, char *butname, IButtonNew *button)
	Save a button to an idDPF. More...
void	SetAlpha (int id, int state, int shade)
	Set the alpha per-surface for the given ID/state. More...
void	SetColorKey (int id, int state, int r, int g, int b)
	Set a colorkey for the given ID/state using RGB values. More...
void	SetColorKey (int id, int state, int CKey)
	Set a colorkey for the given ID/state button using a packed integer. More...
void	SetColorSelect (int id, int r, int g, int b)
	Set the color select to the given ID button. More...
void	SetColorSelect (int id, int rgb)
	Set the color select to the given ID button. More...
void	SetFunction (int id, void(*ButtonFunc)(void *, void *), void *iParam1=NULL, void *iParam2=NULL)
	Set a function for a given ID button. More...
void	SetKey (int id, int keycode)
	Set the assigned key to the given ID button. More...
void	SetLayer (char n)
	Set the working layer. More...
void	SetLayerVisibility (char n, char v)
	Set the visibility flag of a given layer. More...
void	SetMouseButtons (int id, int mousebut)
	Set mouse button sensibility for the given IButton. More...
void	SetName (int id, char *name)
	Set a new name for the given button. More...
void	SetPosition (int id, int x, int y)
	Set position of given ID button. More...
void	SetState (int id, char s)
	Force a state of given ID button. More...
void	SetText (int id, char *)
	Set a text into a button. Only works with InputText button. More...
void	SetTextFont (int id, CRM32Pro_CFont *font)
	Set a font. Only works with InputText button. More...
void	SetTextRect (int id, SDL_Rect *)
	Set text rect area. Only works with InputText button. More...
void	SetValue (int id, int value)
	Set current value of slider or progress. More...
void	SetVisible (int id, unsigned char value)
	Set visibility of given ID button. More...
int	WhoIsSelected (void)
	Get the ID of the selected button. More...

Friends
class	CRM32Pro_Main

Member Function Documentation

int CRM32Pro_IButton::Check

(

void

)

Return the ID of a clicked button without draw anything.

Returns

-1 There isn't any button action

0 to MAX_BUTTON, the ID of the button which generated an action

Examples:

Example03_GUI.cpp.

int CRM32Pro_IButton::Clone

(

int

who

)

Create a clone button from the given Master button ID and put it as a working button on the current layer.

A clone button will use all the current settings of the given Master and its tiles.
After that, you can modify cloned button's settings and they will only affect to the cloned button, neither the Master
nor other cloned buttons are affected. The only thing they always share are the tiles, so you can save a lot of memory if you
have several buttons with the same gfx.
Of course, a cloned button can not work without its Master.

Parameters

who	Master button ID to be cloned

Returns

-1 Failed

0-MAX_BUTTON, the ID of the new cloned button

int CRM32Pro_IButton::Create	(	struct IButtonNew *	button,
		char *	tilename,
		unsigned char	master,
		char *	fDPF
	)

Add a new button to current layer.

It supports alpha per pixel buttons(if the tiles have enabled it).
Note that when you are using alpha per pixel, by its nature, you will have to blit all the background.

Parameters

button	pointer to filled and valid IButtonNew struct
tilename	name of special tile (type "TILB2") to create the button. Is easier to use the EditorDPF
master	0 to create a normal working button. 1 to add this button to the masterbutton list (to be cloned)
fDPF	DPF file that contains the tiles

Returns

-1 Failed

With master = 0, 0 to MAX_BUTTON, the ID of the new created button. This button is added to current working layer.

With master = 1, 1000 to 1000+MAX_MASTERBUTTON, the ID of the master button, ready to be cloned.

int CRM32Pro_IButton::Create	(	struct IButtonNew *	button,
		char *	tilename,
		unsigned char	master,
		int	idDPF
	)

Add new button to current layer.

It supports alpha per pixel buttons(if the tiles have enabled it).
Note that when you are using alpha per pixel, by its nature, you will have to blit all the background.

Parameters

button	pointer to filled and valid IButtonNew struct
tilename	name of special tile (type "TILB2") to create the button. Is better to use DPF-Editor
master	0 to create a normal working button. 1 to add this button to the masterbutton list (to be cloned)
idDPF	ID of the opened DPF which contains the tiles

Returns

With master = 0, 0 to MAX_BUTTON, the ID of the new created button. This button is added to current working layer.

With master = 1, 1000 to 1000+MAX_MASTERBUTTON, the ID of the master button, ready to be cloned.

unsigned char CRM32Pro_IButton::Delete	(	char *	fDPF,
		char *	butname
	)

Delete a button from a DPF file.

Parameters

fDPF	DPF file that contains the button
butname	name of the button to delete

Returns

0 Failed

1 Ok

unsigned char CRM32Pro_IButton::Delete	(	int	idDPF,
		char *	butname
	)

Delete a button from an idDPF.

Parameters

idDPF	ID of the opened DPF
butname	name of the button to delete

Returns

0 Failed

1 Ok

int CRM32Pro_IButton::Draw

(

void

)

Draw current state's buttons of all visible layers returning the ID of clicked button.

Supports multilayers.
Note that layer order is 0(background) to MAX_LAYERBUTTON(foreground).
If you only want to get the ID of a clicked button, use Check().

Returns

-1 There isn't any button action

0 to MAX_BUTTON, the ID of the button which generated an action

Examples:

Example03_GUI.cpp, and SpacePong.cpp.

int CRM32Pro_IButton::GetAlpha	(	int	id,
		int	state
	)

Get alpha blending information.

To extend the information about the alpha blending, you can read How SDL Alpha works (based on SDL documentation).

Parameters

id	button ID
state	specify the desired state: B_NORMAL,B_SELECT,B_PRESS or B_OFF

Returns

-1 Failed

From 0(transparent) to 254(almost full opaque) and alpha per-surface enabled

255 Alpha per-surface disabled

256 Alpha per-pixel enabled

int CRM32Pro_IButton::GetColorKey	(	int	id,
		int	state
	)

Get the current color key.

To unpack the returned value to independent RGB values, you can use SDL_GetRGB().

Parameters

id	button ID
state	specify the desired state: B_NORMAL,B_SELECT,B_PRESS or B_OFF

Returns

-1 Colorkey disabled

Any other positive or 0 value, the packed colorkey on an integer.

int CRM32Pro_IButton::GetColorSelect

(

int

id

)

Get the color select to the given ID button.

Parameters

id

button ID

Returns

packed integer with RGB values.

0 if there is not a color select

int CRM32Pro_IButton::GetKey

(

int

id

)

Get the assigned key to the given ID button.

Parameters

id

button ID

Returns

current keycode assigned to the ID button (see SDL_keysym.h)

0 if there is not an assigned key

char CRM32Pro_IButton::GetLayer

(

void

)

Get the current working layer.

Return the current working layer

Returns

the current working layer. From 0 to MAX_LAYERBUTTON

char CRM32Pro_IButton::GetLayerVisibility

(

char

l

)

Get the visibility of a given layer.

Return the visibility of the given layer

Parameters

l	layer to get the visibility. From 0 to MAX_LAYERBUTTON

Returns

0 means a hidden layer and 1 a visible one.

int CRM32Pro_IButton::GetMouseButtons

(

int

id

)

Get current mouse button sensibility of given IButton.

Parameters

id

button ID

Returns

-1 Failed

CRM32PRO_BUTTON_LEFT when sensibility is set to left mouse button

CRM32PRO_BUTTON_MIDDLE when sensibility is set to middle mouse button

CRM32PRO_BUTTON_RIGHT when sensibility is set to right mouse button

any OR'ed combination of above flags

char * CRM32Pro_IButton::GetName

(

int

id

)

Get the name of a given button.

Parameters

id

button ID

Returns

NULL Failed

any other value, a pointer to button name

int CRM32Pro_IButton::GetNum

(

void

)

Get number of working buttons (clones and normal, not master)

Returns

number of working buttons

int CRM32Pro_IButton::GetRange

(

int

id

)

Get the range of slider or progress.

Parameters

id

button ID

Returns

-1 Failed

any other number, the range value

int CRM32Pro_IButton::GetState

(

int

id

)

Get current state of given ID button.

Parameters

id

button ID

Returns

-1 Failed

any other number, the state

Examples:

Example03_GUI.cpp.

SDL_Surface * CRM32Pro_IButton::GetSurface	(	int	id,
		int	state
	)

Get the surface of the given ID/state button.

Parameters

id	button ID
state	specify the desired state: B_NORMAL,B_SELECT,B_PRESS or B_OFF

Returns

NULL Failed

any other value, a pointer to SDL_Surface

char * CRM32Pro_IButton::GetText

(

int

id

)

Get current text. Only works with InputText button.

Parameters

id	button ID to associate a font

Returns

NULL There is not text available

any other value, a pointer to current text

int CRM32Pro_IButton::GetValue

(

int

id

)

Get current value of slider or progress.

Parameters

id

button ID

Returns

-1 Failed

any other number, the current value

Examples:

Example03_GUI.cpp.

int CRM32Pro_IButton::Info

(

int

m = -1

)

Get useful information.

Parameters

m	-2 only return the total number of buttons
m	-1 dump useful information about all layers and its buttons (default value)
m	>=0 if it is a valid button ID, it will show only its information

Returns

the total number of buttons.

Examples:

Example03_GUI.cpp.

int CRM32Pro_IButton::Load	(	char *	fDPF,
		char *	butname,
		unsigned char	master = 0
	)

Load a button from a specified DPF(using a filename) and add it to current layer.

It supports alpha per pixel buttons.
Note that when you are using alpha per pixel, by its nature, you will have to blit all the background.

Parameters

fDPF	name and optional path of a DPF that contains the button
butname	name of the button to load
master	0 to create a normal working button. 1 to add this button to the masterbutton list (to be cloned)

Returns

-1 Failed

With master = 0, 0 to MAX_BUTTON, the ID of the new created button. This button is added to current working layer.

With master = 1, 1000 to 1000+MAX_MASTERBUTTON, the ID of the master button, ready to be cloned.

Examples:

Example03_GUI.cpp, and SpacePong.cpp.

int CRM32Pro_IButton::Load	(	int	idDPF,
		char *	butname,
		unsigned char	master = 0
	)

Load a button from a specified DPF(using an idDPF) and add it to current layer.

It supports alpha per pixel buttons.
Note that when you are using alpha per pixel, by its nature, you will have to blit all the background.

Parameters

idDPF	ID of the opened DPF
butname	name of the button to load
master	0 to create a normal working button. 1 to add this button to the masterbutton list (to be cloned)

Returns

-1 Failed

With master = 0, 0 to MAX_BUTTON, the ID of the new created button. This button is added to current working layer.

With master = 1, 1000 to 1000+MAX_MASTERBUTTON, the ID of the master button, ready to be cloned.

unsigned char CRM32Pro_IButton::LoadHeader	(	char *	fDPF,
		char *	butname,
		IButtonNew *	info
	)

Only load the button header from a DPF file.

Parameters

fDPF	DPF file to store it
butname	name of the button to load header
info	struct filled with button header

Returns

0 Failed

1 Ok

unsigned char CRM32Pro_IButton::LoadHeader	(	int	idDPF,
		char *	butname,
		IButtonNew *	info
	)

Only load the button header from an idDPF.

Parameters

idDPF	ID of the opened DPF
butname	name of the button to load header
info	struct filled with button header

Returns

0 Failed

1 Ok

void CRM32Pro_IButton::Remove

(

int

id

)

Remove a button given its ID.

Parameters

id	button ID to delete

void CRM32Pro_IButton::RemoveMaster

(

int

id

)

Remove a master button given its ID.

Parameters

id	master button ID. -1 to remove all master buttons

int CRM32Pro_IButton::Save	(	char *	fDPF,
		char *	butname,
		IButtonNew *	button
	)

Save a button to a DPF file.

Parameters

fDPF	name and optional path of a DPF to store the button
butname	name of the button and tile name(special type "TILB2") to generate the button. Is better to use DPF-Editor
button	filled and valid IButtonNew struct

Returns

-7 Error: incorrect range and/or value

-6 Error: incorrect key code selected

-5 Error: select tile not found (butname with suffix "_s" and type "TILB2")

-4 Error: off tile not found (butname with suffix "_o" and type "TILB2")

-3 Error press tile not found (butname with suffix "_p" and type "TILB2")

-2 Error: normal tile not found (butname with suffix "_n" and type "TILB2")

-1 Button already exists.

0 Error: wrong parameters or internal error

any other positive value, Ok and packed size of the added button

int CRM32Pro_IButton::Save	(	int	idDPF,
		char *	butname,
		IButtonNew *	button
	)

Save a button to an idDPF.

Parameters

idDPF	ID of the opened DPF
butname	name of the button and tile name(special type "TILB2") to generate the button. Is better to use DPF-Editor
button	filled and valid IButtonNew struct

Returns

-7 Error: incorrect range and/or value

-6 Error: incorrect key code selected

-5 Error: select tile not found (butname with suffix "_s" and type "TILB2")

-4 Error: off tile not found (butname with suffix "_o" and type "TILB2")

-3 Error press tile not found (butname with suffix "_p" and type "TILB2")

-2 Error: normal tile not found (butname with suffix "_n" and type "TILB2")

-1 Button already exists.

0 Error: wrong parameters or internal error

any other positive value, Ok and packed size of the added button

void CRM32Pro_IButton::SetAlpha	(	int	id,
		int	state,
		int	shade
	)

Set the alpha per-surface for the given ID/state.

A surface with enabled alpha blending(per-pixel or per-surface) will be never created on video memory if alpha blending is not supported by the hardware. Right now, only glSDL supports it.
With per-pixel alpha, per-surface alpha is useless, so any attempt to activate it will be ignored.

Note that enabling and disabling the alpha blending on the execution time could slowdown your graphic performance.
To extend the information about the alpha blending, you can read How SDL Alpha works (based on SDL documentation).

Parameters

id	button ID
state	specify the desired state: B_NORMAL,B_SELECT,B_PRESS or B_OFF. 0 to set the alpha on all states.
shade	integer from 0(transparent) to 254(almost full opaque) to enable the per-surface alpha or 255(full opaque) to disable it.

void CRM32Pro_IButton::SetColorKey	(	int	id,
		int	state,
		int	r,
		int	g,
		int	b
	)

Set a colorkey for the given ID/state using RGB values.

With alpha per pixel, colorkey is useless.

Parameters

id	button ID
state	specify the desired state: B_NORMAL,B_SELECT,B_PRESS or B_OFF. 0 to set the colorkey on all states.
r	red component (0-255). -1 to disable the colorkey.
g	green component (0-255). -1 to disable the colorkey.
b	blue component (0-255). -1 to disable the colorkey.

void CRM32Pro_IButton::SetColorKey	(	int	id,
		int	state,
		int	CKey
	)

Set a colorkey for the given ID/state button using a packed integer.

To pack the integer with RGB values, you can use SDL_MapRGB().
With alpha per pixel, colorkey is useless.

Parameters

id	button ID
state	specify the desired state: B_NORMAL,B_SELECT,B_PRESS or B_OFF. 0 to set the colorkey on all states.
CKey	packed integer with colorkey. You also can use -1 to disable the colorkey.

void CRM32Pro_IButton::SetColorSelect	(	int	id,
		int	r,
		int	g,
		int	b
	)

Set the color select to the given ID button.

The RGB component will be adjusted to the internal RGB format of the button.
To disable it, use as r,g,b values 0

Parameters

id	button ID
r	red component (0-255).
g	green component (0-255).
b	blue component (0-255).

void CRM32Pro_IButton::SetColorSelect	(	int	id,
		int	rgb
	)

Set the color select to the given ID button.

The color select will be directly assigned to the button you have to be carefully about its format.

Parameters

id	button ID
rgb	packed integer with desired RGB values. 0 to disable the color select.

void CRM32Pro_IButton::SetFunction	(	int	id,
		void(*)(void *, void *)	ButtonFunc,
		void *	iParam1 = NULL,
		void *	iParam2 = NULL
	)

Set a function for a given ID button.

Parameters

id	button ID
ButtonFunc	pointer to function that will be executed with action state
iParam1	Optional void pointer to desired data type to be passed to the function
iParam2	Optional void pointer to desired data type to be passed to the function

Examples:

Example03_GUI.cpp.

void CRM32Pro_IButton::SetKey	(	int	id,
		int	keycode
	)

Set the assigned key to the given ID button.

Parameters

id	button ID
keycode	desired keycode (see SDL_keysym.h). Use 0 to remove any previous assigned key

void CRM32Pro_IButton::SetLayer

(

char

n

)

Set the working layer.

Used to add/remove buttons.
Note that using this function will remove any previous visibility layers.

Parameters

n	layer to activate as the current one. From 0 to MAX_LAYERBUTTON

Examples:

Example03_GUI.cpp.

void CRM32Pro_IButton::SetLayerVisibility	(	char	n,
		char	v
	)

Set the visibility flag of a given layer.

A layer with its visibility flag set to visible will allow to Draw() member to check/draw all its buttons.
Note that using this function will hold previous visibility layers.

Parameters

n	layer to set the visibility. From 0 to MAX_LAYERBUTTON
v	0 means a hidden layer and 1 means a visible layer.

void CRM32Pro_IButton::SetMouseButtons	(	int	id,
		int	mousebut
	)

Set mouse button sensibility for the given IButton.

Parameters

id	button ID
mousebut	CRM32PRO_BUTTON_LEFT,CRM32PRO_BUTTON_MIDDLE,CRM32PRO_BUTTON_RIGHT or any OR'ed combination

void CRM32Pro_IButton::SetName	(	int	id,
		char *	name
	)

Set a new name for the given button.

Parameters

id	button ID
name	pointer to the new name. Maximum of 24 characters.

void CRM32Pro_IButton::SetPosition	(	int	id,
		int	x,
		int	y
	)

Set position of given ID button.

Parameters

id	button ID
x	position x
y	position y

void CRM32Pro_IButton::SetState	(	int	id,
		char	s
	)

Force a state of given ID button.

It is usually used to disabled a given button.

Parameters

id	button ID
s	force to set current state of button id to the given state. See definition of B_NORMAL, B_OFF, etc.

Examples:

SpacePong.cpp.

void CRM32Pro_IButton::SetText	(	int	id,
		char *	text
	)

Set a text into a button. Only works with InputText button.

Parameters

id	button ID to associate a font
text	string with desired text.

Examples:

Example03_GUI.cpp.

void CRM32Pro_IButton::SetTextFont	(	int	id,
		CRM32Pro_CFont *	font
	)

Set a font. Only works with InputText button.

It automatically does a Y centered text position.
Note you have to manage this font (load and delete)
By safety reasons, you should set to NULL the font pointer as soon as you delete the font.

Parameters

id	button ID to associate a font
font	pointer to initialized font.

Examples:

Example03_GUI.cpp.

void CRM32Pro_IButton::SetTextRect	(	int	id,
		SDL_Rect *	rect
	)

Set text rect area. Only works with InputText button.

By default, text rect area is the whole button surface and the text is Y centered.

Parameters

id	button ID to associate a font
rect	pointer to initialized rect with coordinates and sizes relatives to the button position.

void CRM32Pro_IButton::SetValue	(	int	id,
		int	value
	)

Set current value of slider or progress.

Parameters

id	button ID
value	current value

Examples:

Example03_GUI.cpp.

void CRM32Pro_IButton::SetVisible	(	int	id,
		unsigned char	value
	)

Set visibility of given ID button.

Parameters

id	button ID
value	0=hide and 1=show

int CRM32Pro_IButton::WhoIsSelected

(

void

)

Get the ID of the selected button.

Supports multilayers.
Note that layer order is 0(background) to MAX_LAYERBUTTON(foreground).

Returns

-1 There isn't any selected button

0 to MAX_BUTTON, the ID of a selected button

---

The documentation for this class was generated from the following files:

• CRM32Pro.h
• 10_Button.cpp