Lists for the MrMWidgets. More...

Functions
Lists management functions
These functions create and handle lists.
int	mrmListInit (int scr, int width, int height, int wwidth, int mode, char *texts, void(callBack)(int, int, int), int items, char *title)
	Creates a new list with the given parameters. More...

int	mrmListDelete (int idx)
	Delete the list whose reference number is given. More...

int	mrmListSetEnabled (int idx, int enabled)
	Enable or disable list. More...

int	mrmListSetPos (int idx, int x, int y)
	Places the list at the given position on the screen. More...

int	mrmListSetSize (int idx, int w, int h, int ww)
	Resizes the list. More...

int	mrmListSetColor (int idx, int col, int dCol, int sCol, int wCol, int wBCol, int wW1Col, int wW2Col)
	Sets the colors for the list. More...

int	mrmListSetFont (int idx, int sz, int a, char *fn, int s)
	Sets the font for the list contents. More...

int	mrmListSetFontColor (int idx, int nCol, int dCol, int tsCol)
	Sets the colors for the list texts. More...

int	mrmListAddItems (int idx, char **items)
	Adds contents to the list. More...

int	mrmListInsertItem (int idx, int pos, char *item)
	Insert an item in a given position of the list. More...

int	mrmListDelItem (int idx, int pos)
	Deletes the item at the given position of the list. More...

int	mrmListSetSelected (int idx, int sel)
	Sets the value of the selection of the list. More...

int	mrmListGetSelected (int idx)
	Reads the value of the selection of the list. More...

int	mrmListItemAtIndex (int idx, int pos, char *string)
	Reads the text of the given index. More...

Detailed Description

Author: Germán Fabregat

Date: October 2017

Function Documentation

◆ mrmListInit()

int mrmListInit	(	int	scr,
		int	width,
		int	height,
		int	wwidth,
		int	mode,
		char **	texts,
		void(*)(int, int, int)	callBack,
		int	items,
		char *	title
	)

This function is used to create a List of the given width and height on the given screen. Two colors are also given; the normal color, and the color to be used when the List is disabled. The List is enabled after creation, but it is not placed on screen -and thus visible and usable- until its position is set using the corresponding function. The maximum number of characters to be read is also specified, as well as the type of keyboard -alphanueric or numeric- used to enter the text. A callback function can be specified to be called when the user opens the list window or selects an element of the list. This function will receive three integer parameters: the List reference, the screen index and MWG_LIOPEN if the user has opened the list window by clicking on it, MWG_LICLOSE if the user has closed the window without making a selection or MWG_LISELECT if the user has closed the window and made a selection.

Parameters

[in]	scr	Graphic screen where the List is placed.
[in]	width	Width in pixels of the List on screen.
[in]	height	Height in pixels of the List.
[in]	wwidth	Width in pixels of the window to display the List, not considering borders.
[in]	mode	It can be MWG_LIORDERED to keep the items alphabetically ordered or MWG_LINONE otherwise.
[in]	texts	NULL terminated array of pointers to the initial texts of the list.
[in]	callBack	Function to be called when the user opens or selects an element of the list. If NULL no function is invoked.
[in]	items	Number of elements to be displayed on the pop up window.
[in]	title	Caption for the pop up window.

Returns: The function returns a 0 or positive integer that references the created List, or a negative value if an error occurred.

◆ mrmListDelete()

int mrmListDelete ( int idx )

This functions deletes from the system the list whose reference number is given, releasing all associated resources. The reference number and list slot are released for further use.

Parameters

[in] idx List reference number.

Returns: A negative value in case of error, positive otherwise.

◆ mrmListSetEnabled()

int mrmListSetEnabled	(	int	idx,
		int	enabled
	)

This functions sets the enabled state of the list. When a list is disabled it appears with the disabled colors and cannot be used to select item.

Parameters

[in]	idx	List reference number.
[in]	enabled	0 to disable the list, nonzero to enable.

Returns: A negative value in case of error, positive otherwise.

◆ mrmListSetPos()

int mrmListSetPos	(	int	idx,
		int	x,
		int	y
	)

For a list to be displayed on its screen it has to be placed on a given position. This function has to be used to place the list at the desired x,y position on the screen.

Parameters

[in]	idx	List reference number.
[in]	x	Horizontal coordinate of the top left corner of the list.
[in]	y	Vertical coordinate of the top left corner of the list.

Returns: A negative value in case of error, positive otherwise.

◆ mrmListSetSize()

int mrmListSetSize	(	int	idx,
		int	w,
		int	h,
		int	ww
	)

This function changes the height, the width of the button or both.

Parameters

[in]	idx	List reference number.
[in]	w	New width of the list. If 0 let it unchanged.
[in]	h	New height of the list. If 0 let it unchanged.
[in]	ww	New width of the list window. If 0 let it unchanged.

Returns: A negative value in case of error, positive otherwise.

◆ mrmListSetColor()

int mrmListSetColor	(	int	idx,
		int	col,
		int	dCol,
		int	sCol,
		int	wCol,
		int	wBCol,
		int	wW1Col,
		int	wW2Col
	)

When a list is created it is given default colors. This function allows the user to change them during execution.

Parameters

[in]	idx	List reference number.
[in]	col	Color for the list.
[in]	dCol	Color for the list when disabled.
[in]	sCol	Color for the selected item background on the list window.
[in]	wCol	Color for the background of the list window.
[in]	wW1Col	Main color for the widgets of the list window.
[in]	wW2Col	Secondary color for the widgets of the list window.

Returns: A negative value in case of error, positive otherwise.

◆ mrmListSetFont()

int mrmListSetFont	(	int	idx,
		int	sz,
		int	a,
		char *	fn,
		int	s
	)

When a list is created its text is assigned default font and colors. This function allows to set the font for the text contained on the box and the window text.

Parameters

[in]	idx	List reference number.
[in]	sz	Size of the font.
[in]	a	Rotation angle in degrees.
[in]	fn	Pointer to a string containing the font name. If it is NULL the standard font is used.
[in]	s	Style of the font. The three lower bits mean from 0 to 2 italic, underline and strikeout. The higher bits a weight ranging from 0 to 1000. The constants MGS_ITALIC, MGS_UNDERLINE and MGS_STRIKEOUT can be ored to form the lower three bits. MGS_LIGHT, MGS_BOLD and MGS_HEAVY are three predefined values for the weight that can also be ored.

Returns: A negative value in case of error, positive otherwise.

◆ mrmListSetFontColor()

int mrmListSetFontColor	(	int	idx,
		int	nCol,
		int	dCol,
		int	tsCol
	)

When a list is created its text is assigned default font and colors. This function allows to set colors for the text contained on the box and the window text.

Parameters

[in]	idx	List reference number.
[in]	nCol	Color for the list text.
[in]	dCol	Color for the list text when disabled.
[in]	tsCol	Color for the selected item text on the list window.

Returns: A negative value in case of error, positive otherwise.

◆ mrmListAddItems()

int mrmListAddItems	(	int	idx,
		char **	items
	)

Adds a NULL terminated list of strings to the list options. They are added at the end or ordered alphabetically, according to the order settings of the list. It does not check for identical texts. The selected option is reset

Parameters

[in]	idx	List reference number.
[in]	items	NULL terminated list of strings.

Returns: A negative value in case of error or the number of items added.

◆ mrmListInsertItem()

int mrmListInsertItem	(	int	idx,
		int	pos,
		char *	item
	)

Adds a new string to the list options before the given position, disregarding the order. If the position is out of the list the fuction does nothing. It does not check for identical texts. The selected option is not reset

Parameters

[in]	idx	List reference number.
[in]	pos	Position of the item, starting at 0.
[in]	item	Text to be added.

Returns: A negative value in case of error, positive otherwise.

◆ mrmListDelItem()

int mrmListDelItem	(	int	idx,
		int	pos
	)

Deletes the element of the given position of the list. If the position is out of the list the fuction does nothing. The selected option is not reset.

Parameters

[in]	idx	List reference number.
[in]	pos	Position of the item, starting at 0.

Returns: A negative value in case of error, positive otherwise.

◆ mrmListSetSelected()

int mrmListSetSelected	(	int	idx,
		int	sel
	)

This function sets the item currenlty selected on the list, and returns the old selected one. If the index is out of range the change is ignored.

Parameters

[in]	idx	List reference number.
[in]	sel	Index of the new selected item.

Returns: The index of the previously selected item or MGS_ERRRESNOEXIST in case the list does not exist.

◆ mrmListGetSelected()

int mrmListGetSelected ( int idx )

This function reads the index of the item currenlty selected on the list.

Parameters

[in] idx List reference number.

Returns: The index of the selected item or MGS_ERRRESNOEXIST in case the list does not exist.

◆ mrmListItemAtIndex()

int mrmListItemAtIndex	(	int	idx,
		int	pos,
		char *	string
	)

This function copies the contents of the text of the given item to the given string. This must have enough space to hold the whole text as no size checking is performed.

Parameters

[in]	idx	List reference number.
[in]	pos	Index of the item whose text is to be read.
[out]	string	String to receive the contents. It must have the required space.

Returns: A positive value in case of success or a negative one in case of error.

Functions

Detailed Description

Function Documentation

◆ mrmListInit()

◆ mrmListDelete()

◆ mrmListSetEnabled()

◆ mrmListSetPos()

◆ mrmListSetSize()

◆ mrmListSetColor()

◆ mrmListSetFont()

◆ mrmListSetFontColor()

◆ mrmListAddItems()

◆ mrmListInsertItem()

◆ mrmListDelItem()

◆ mrmListSetSelected()

◆ mrmListGetSelected()

◆ mrmListItemAtIndex()