user/interface/InterfaceDefs.dox

/*
 * Copyright 2011-2013 Haiku, Inc. All rights reserved.
 * Distributed under the terms of the MIT License.
 *
 * Authors:
 *		John Scipione, jscipione@gmail.com
 *
 * Corresponds to:
 *		headers/os/interface/InterfaceDefs.h	hrev45737
 *		src/kits/interface/InterfaceDefs.cpp	hrev45737
 */


/*!
	\file InterfaceDefs.h
	\ingroup interface
	\ingroup libbe
	\brief Defines standard interface definitions for controls.

	\since BeOS R3
*/


/*!
	\enum color_which {
	\ingroup interface

	System default colors.
	If you want to use these make sure to always pick a matching set for your foreground and
	 background.
	For example B_PANEL_TEXT_COLOR goes ontop of B_PANEL_BACKGROUND_COLOR.

	\since Haiku R1
*/


/*!
	\var color_which B_NO_COLOR

	This indicates that no color has been configured for the View.

	\since Haiku R1
*/


/*!
	\var color_which B_PANEL_BACKGROUND_COLOR

	The background color of a panel, a panel in this context is a window area on which controls are
	 added.
	For example the background of preferences/appearence

	use with B_PANEL_TEXT_COLOR

	\since BeOS
*/


/*!
	\var color_which B_PANEL_TEXT_COLOR

	The text color matching B_PANEL_BACKGROUND_COLOR.

	\since Haiku R1
*/


/*!
	\var color_which B_DOCUMENT_BACKGROUND_COLOR

	The background color of a text view.
	For example the background of a BTextView.

	use with B_DOCUMENT_TEXT_COLOR

	\since Haiku R1
*/


/*!
	\var color_which B_DOCUMENT_TEXT_COLOR

	The text color matching B_DOCUMENT_BACKGROUND_COLOR.

	\since Haiku R1
*/


/*!
	\var color_which B_CONTROL_BACKGROUND_COLOR

	The background of a control.
	For example a Button.

	use with B_CONTROL_TEXT_COLOR

	\since Haiku R1
*/


/*!
	\var color_which B_CONTROL_TEXT_COLOR

	The text color matching B_CONTROL_BACKGROUND_COLOR.

	\since Haiku R1
*/


/*!
	\var color_which B_CONTROL_BORDER_COLOR

	The border of a control.
	For example a Button.

	use with B_CONTROL_BACKGROUND_COLOR

	\since Haiku R1
*/


/*!
	\var color_which B_CONTROL_HIGHLIGHT_COLOR

	\since Haiku R1
*/


/*!
	\var color_which B_CONTROL_MARK_COLOR

	\since Haiku R1
*/


/*!
	\var color_which B_NAVIGATION_BASE_COLOR

	This is used to the keyboard focus.

	\since Haiku R1
*/


/*!
	\var color_which B_NAVIGATION_PULSE_COLOR

	\since Haiku R1
*/


/*!
	\var color_which B_SHINE_COLOR

	\deprecated This should not be used anymore.

	\since Haiku R1
*/


/*!
	\var color_which B_SHADOW_COLOR

	\deprecated This should not be used anymore.

	\since Haiku R1
*/


/*!
	\var color_which B_LINK_TEXT_COLOR

	The color of links (URLs).

	\since Haiku R1
*/


/*!
	\var color_which B_LINK_HOVER_COLOR

	The color of a link (URL) that is currently hovered by the mouse.

	\since Haiku R1
*/


/*!
	\var color_which B_LINK_VISITED_COLOR

	The color of a link (URL) that was visited in the past.

	\since Haiku R1
*/


/*!
	\var color_which B_LINK_ACTIVE_COLOR

	The color of a link (URL) that is active.
	This is a link that is currently beeing clicked, but the user has not yet let go of the mouse.

	\since Haiku R1
*/


/*!
	\var color_which B_MENU_BACKGROUND_COLOR

	The background color of a menu.

	\since BeOS
*/


/*!
	\var color_which B_MENU_SELECTED_BACKGROUND_COLOR

	The background color of selected menu item.

	Relates to B_MENU_BACKGROUND_COLOR

	\since Haiku R1
*/


/*!
	\var color_which B_MENU_ITEM_TEXT_COLOR

	The text color of a menu item.

	Use with B_MENU_BACKGROUND_COLOR.

	\since BeOS
*/


/*!
	\var color_which B_MENU_SELECTED_ITEM_TEXT_COLOR

	The text color of a selected menu item.

	Use with B_MENU_SELECTED_BACKGROUND_COLOR.

	\since BeOS
*/


/*!
	\var color_which B_MENU_SELECTED_BORDER_COLOR

	\deprecated This should not be used anymore.

	\since Haiku R1
*/


/*!
	\var color_which B_LIST_BACKGROUND_COLOR

	The background color of a list.
	This is used by BListView.

	\since Haiku R1
*/


/*!
	\var color_which B_LIST_SELECTED_BACKGROUND_COLOR

	The background color of a selected list item.

	\since Haiku R1
*/


/*!
	\var color_which B_LIST_ITEM_TEXT_COLOR

	The text color of a list item.

	Use with B_LIST_BACKGROUND_COLOR.

	\since Haiku R1
*/


/*!
	\var color_which B_LIST_SELECTED_ITEM_TEXT_COLOR

	The text color of a selected list item.

	Use with B_LIST_SELECTED_BACKGROUND_COLOR.

	\since Haiku R1
*/


/*!
	\var color_which B_SCROLL_BAR_THUMB_COLOR

	The color of the thumb of a scrollbar.
	This is the part you can drag.

	\since Haiku R1
*/


/*!
	\var color_which B_TOOL_TIP_BACKGROUND_COLOR

	The background color of a tooltip.

	\since Haiku R1
*/


/*!
	\var color_which B_TOOL_TIP_TEXT_COLOR

	The text color of a tooltip.

	Use with B_TOOL_TIP_BACKGROUND_COLOR.

	\since Haiku R1
*/


/*!
	\var color_which B_STATUS_BAR_COLOR

	This is used by progress bars.
	For example by BStatusBar.

	\since Haiku R1
*/


/*!
	\var color_which B_SUCCESS_COLOR

	This marks operations that suceeded.
	For example downloads in WebPositive that completed.

	\since Haiku R1
*/


/*!
	\var color_which B_FAILURE_COLOR

	This marks operations that failed.
	For example downloads in WebPositive that failed or wrong user input.
	Used by BTextControl::MarkAsInvalid

	\since Haiku R1
*/


/*!
	\var color_which B_WINDOW_TAB_COLOR

	The background color of the active window tab.

	\since BeOS
*/


/*!
	\var color_which B_WINDOW_TEXT_COLOR

	The text color of the active window tab.

	Use with B_WINDOW_TAB_COLOR.

	\since Haiku R1
*/


/*!
	\var color_which B_WINDOW_INACTIVE_TAB_COLOR

	The background color of inactive window tabs.

	\since Haiku R1
*/


/*!
	\var color_which B_WINDOW_INACTIVE_TEXT_COLOR

	The text color of inactive window tabs.

	Use with B_WINDOW_INACTIVE_TAB_COLOR.

	\since Haiku R1
*/


/*!
	\var color_which B_WINDOW_BORDER_COLOR

	The border color of the active window.

	Relates to B_WINDOW_TAB_COLOR.

	\since Haiku R1
*/


/*!
	\var color_which B_WINDOW_INACTIVE_BORDER_COLOR

	The border color of the inactive windows.

	Relates to B_WINDOW_INACTIVE_TAB_COLOR.

	\since Haiku R1
*/


/*!
	\enum border_style
	\ingroup interface

	Collection of flags that determine the border style drawn around a BBox.

	\since BeOS R3
*/


/*!
	\var border_style B_PLAIN_BORDER

	\image html B_PLAIN_BORDER.png

	The right and bottom sides of the box are darker than the top and
	left sides to produce a shadow effect and make the box look like it
	is raised slightly above the surrounding surface.

	\since BeOS R3
*/


/*!
	\var border_style B_FANCY_BORDER

	\image html B_FANCY_BORDER.png

	The border is a bevelled to give it a 3D effect. The border is uniform
	in appearance on all four sides. This is the default appearance.

	\since BeOS R3
*/


/*!
	\var border_style B_NO_BORDER

	No border.

	\since BeOS R3
*/


/*!
	\enum orientation

	Orientation flag sets the layout to either horizontal or vertical
	alignment.

	\since BeOS R3
*/


/*!
	\var orientation B_HORIZONTAL

	Horizontal alignment

	\since BeOS R3
*/


/*!
	\var orientation B_VERTICAL

	Vertical alignment

	\since BeOS R3
*/


/*!
	\enum button_width

	Collection of flags that determine how wide to draw the buttons in a
	BAlert dialog.

	\since BeOS R3
*/


/*!
	\var button_width B_WIDTH_AS_USUAL

	Set the width of each button based on the standard width.

	\since BeOS R3
*/


/*!
	\var button_width B_WIDTH_FROM_WIDEST

	Set the width of each button based on the width of the widest button.

	\since BeOS R3
*/


/*!
	\var button_width B_WIDTH_FROM_LABEL

	Set the width of each button to accommodate the label.

	\since BeOS R5
*/


// Line join and cap modes


/*!
	\enum join_mode

	PostScript-style line join modes used by BView::SetLineMode()

	\since BeOS R3
*/


/*!
	\var join_mode B_ROUND_JOIN

	Round join mode.

	\since BeOS R3
*/


/*!
	\var join_mode B_MITER_JOIN

	Miter join mode.

	\since BeOS R3
*/


/*!
	\var join_mode B_BEVEL_JOIN

	Bevel join mode.

	\since BeOS R3
*/


/*!
	\var join_mode B_BUTT_JOIN

	Butt join mode.

	\since BeOS R3
*/

/*!
	\var join_mode B_SQUARE_JOIN

	Square join mode.

	\since BeOS R3
*/


/*!
	\enum cap_mode

	PostScript-style line cap modes used by BView::SetLineMode()

	\since BeOS R3
*/


/*!
	\var cap_mode B_ROUND_CAP

	Round cap mode.

	\since BeOS R3
*/


/*!
	\var cap_mode B_BUTT_CAP

	Butt cap mode.

	\since BeOS R3
*/


/*!
	\var cap_mode B_SQUARE_CAP

	Square cap mode.

	\since BeOS R3
*/


/*!
	\var B_DEFAULT_MITER_LIMIT

	Default miter limit used to calculate the angle cut off for miter joins.

	\since BeOS R3
*/


///// Keyboard related functions


/*!
	\fn uint32 modifiers()
	\brief Gets a bitmap of each modifier key pressed down and each active
		keyboard lock.

	Test the bitmap returned using a bit mask composed of the following
	modifier key constants:
		- \c B_CAPS_LOCK
		- \c B_COMMAND_KEY
		- \c B_CONTROL_KEY
		- \c B_MENU_KEY
		- \c B_NUM_LOCK
		- \c B_OPTION_KEY
		- \c B_SCROLL_LOCK
		- \c B_SHIFT_KEY

	You may use a bit mask of 0 to test that no modifier keys are pressed.
	If it is important to know if the left or right modifier key is pressed
	down you can use the following additional constants:
		- \c B_LEFT_SHIFT_KEY
		- \c B_RIGHT_SHIFT_KEY
		- \c B_LEFT_CONTROL_KEY
		- \c B_RIGHT_CONTROL_KEY
		- \c B_LEFT_OPTION_KEY
		- \c B_RIGHT_OPTION_KEY
		- \c B_LEFT_COMMAND_KEY
		- \c B_RIGHT_COMMAND_KEY

	\returns A bitmap containing each active modifier keys and locks.

	\since BeOS R3
*/


/*!
	\fn status_t get_key_info(key_info* info)
	\brief Fills out the key_info struct with the current state of the
		keyboard.

	\param info The key_info struct to fill out.

	\retval B_OK Everything went fine.
	\retval B_ERROR There was an error retrieving the key_info struct.

	\since BeOS R3
*/


/*!
	\fn void get_key_map(key_map** _map, char** _keyBuffer)
	\brief Provides a copy of the system keymap.

	\attention You must free \a _map and \a _keyBuffer when you are done
		with them.

	\param _map A pointer to the system keymap structure.
	\param _keyBuffer A pointer containing the UTF-8 character encodings.

	\since BeOS R3
*/


/*!
	\fn status_t get_keyboard_id(uint16* _id)
	\brief Fills out \a _id with the id of the currently attached keyboard.

	\retval B_OK Everything went fine.
	\retval B_ERROR There was an error retrieving the keyboard id.

	\since BeOS R3
*/


/*!
	\fn status_t get_modifier_key(uint32 modifier, uint32 *key)
	\brief Gets the code of the requested \a modifier key from the
		system keymap.

	\param modifier The modifier key to get from the system keymap.
	\param key A pointer to an int32 to store the key code.

	\retval B_OK Everything went fine.
	\retval B_ERROR There was an error retrieving the modifier key.

	\since BeOS R3
*/


/*!
	\fn void set_modifier_key(uint32 modifier, uint32 key)
	\brief Set the \a modifier \a key to the specified code in the
		system keymap.

	\param modifier The modifier key to set in the system keymap.
	\param key The key code to set the modifier key to.

	\since BeOS R3
*/


/*!
	\fn void set_keyboard_locks(uint32 modifiers)
	\brief Set the keyboard locks.

	Pass in a bit mask containing the following constants:
		- \c B_CAPS_LOCK
		- \c B_NUM_LOCK
		- \c B_SCROLL_LOCK

	The constants present in the bit mask will turn the lock on, those
	absent will turn the lock off. Pass 0 in to turn off all locks.

	\param modifiers A bitmap of lock keys to set.

	\since BeOS R3
*/


/*!
	\fn status_t get_mouse_type(int32* type)
	\brief Get the number of buttons of the mouse.

	If there are multiple mouses connected, the number of buttons for one of
	them picked at random will be returned.

	\deprecated Use \ref "get_mouse_type(const char* mouse_name, int32* type)"
		instead.
*/


/*!
	\fn status_t get_mouse_type(const char* mouse_name, int32* type)
	\brief Get the number of buttons for a specific mouse.

	Mouse names can be known from BInputDevice.

	\since Haiku R1
*/


/*!
	\fn status_t set_mouse_type(const char* mouse_name, int32 type)
	\brief Configure the number of buttons for a specific mouse.

	The setting is saved and persists accross reboots.

	\since Haiku R1
*/


/*!
	\fn status_t get_mouse_map(mouse_map* map)
	\brief Get the button map of the mouse.

	\deprecated Use \ref "get_mouse_map(const char* mouse_name, mouse_map* map)"
		instead.
*/


/*!
	\fn status_t get_mouse_map(const char* mouse_name, mouse_map* map)
	\brief Get the button map for a specific mouse.

	\since Haiku R1
*/


/*!
	\fn status_t set_mouse_map(mouse_map* map)
	\brief Set the button map of the mouse.

	\deprecated Use \ref "set_mouse_map(const char* mouse_name, mouse_map* map)"
		instead.
*/


/*!
	\fn status_t set_mouse_map(const char* mouse_name, mouse_map* map)
	\brief Set the button map for a specific mouse.

	The setting is saved and persists accross reboots.

	\since Haiku R1
*/


/*!
	\fn status_t get_click_speed(bigtime_t* speed)
	\brief Get the double-click maximum delay.

	\deprecated Use \ref "get_click_speed(const char* mouse_name, bigtime_t* speed)"
		instead.
*/


/*!
	\fn status_t get_click_speed(const char* mouse_name, bigtime_t* speed)
	\brief Get the double-click maximum delay for a specific mouse.

	\since Haiku R1
*/


/*!
	\fn status_t set_click_speed(bigtime_t speed)
	\brief Set the double-click maximum delay.

	\deprecated Use \ref "get_click_speed(const char* mouse_name, bigtime_t* speed)"
		instead.
*/


/*!
	\fn status_t set_click_speed(const char* mouse_name, bigtime_t speed)
	\brief Set the double-click maximum delay for a specific mouse.

	\since Haiku R1
*/


/*!
	\fn status_t get_mouse_speed(int32* speed)
	\brief Get the mouse speed.

	If there are multiple mouses connected, this function returns the speed
	from a random one.

	\deprecated Use \ref "get_mouse_speed(const char* mouse_name, int32* speed)"
		instead.
*/


/*!
	\fn status_t get_mouse_speed(const char* mouse_name, int32* speed)
	\brief Get the mouse speed setting for a specific mouse.

	\since Haiku R1
*/


/*!
	\fn status_t set_mouse_speed(const char* mouse_name, int32 speed)
	\brief Set the mouse speed for a specific mouse.

	The setting is saved and persists accross reboots.

	\since Haiku R1
*/


/*!
	\fn status_t get_mouse_acceleration(int32* speed)
	\brief Get the mouse acceleration.

	If there are multiple mouses connected, this function returns the speed
	from a random one.

	\deprecated Use \ref "get_mouse_acceleration(const char* mouse_name, int32* speed)"
		instead.
*/


/*!
	\fn status_t get_mouse_acceleration(const char* mouse_name, int32* speed)
	\brief Get the mouse acceleration setting for a specific mouse.

	\since Haiku R1
*/


/*!
	\fn status_t set_mouse_acceleration(const char* mouse_name, int32 speed)
	\brief Set the mouse acceleration for a specific mouse.

	The setting is saved and persists accross reboots.

	\since Haiku R1
*/