tsc_ButtonControl

A tsc_ButtonControl provides a standard pushbutton control for use on forms.

As can be seen from the image to the right, a button may contain text, an image, or both.  The content of the button (ie, the text and/or the image) may be aligned independently. If no alignment or size is specified for the button, the control will attempt its best to make something that looks good. The result may then be tuned using the various alignment and sizing methods.

A background image may also be supplied, which will occupy the entire button unless the button is given a custom size which is different from the image size.

The area for the foreground image may be defined by specifying padding values for the top, right, bottom, and left sides of the button. A default of about 8% of the size of the button on each of the four sides is used if the padding is not set.  The image may be aligned to an edge, or centered either vertically and/or horizontally, within the content area.

The area for the text is defined by a padding value and an alignment option. Like the image, the text may be aligned to an edge or centered, both horizontally and vertically. The padding applies to all sides and is given as a percentage of the width, which allow it to scale with the button width. The computed number of pixels is used on all four sides.

The size of the button is determined by a number of factors.  All buttons on a form which uses automatic layout (Layout_Auto) will be made the standard size.  On custom layouts, the default is for the button to be sized to the content (the text or image, depending on the constructor used), or this may be overridden by calling SetCustomDimensions.  

To obtain a full-sized background image it is easiest to avoid SetCustomDimensions and instead make the background image to the size desired for the button.

More information about how colours, images, and text are drawn in layers on the button can be found further down this page.

Public constructors

The constructor used determines the type of button (text, image, or both) that is created.  While it is possible to add an image to a text button, or add text to an image button, the size of the button is determined by the constructor used.  On a form using automatic layout (Layout_Auto), the button will by default be the standard size, however most methods that control the color, size, and content layout can be used to full effect - although making the button too big may compromise the form layout.

tsc_ButtonControl (x_Code identifier);

Creates a text button control.  The text of the button is set from the translated identifier.  The text and/or image may be changed or added with the SetText and SetImage methods.  Unless otherwise specified, the size of the button is set to the size of the translated text, plus the padding.

tsc_ButtonControl (x_Code identifier, const char* text);

Creates a text button control with the specified text.  The text may be changed or an image added with the SetText and SetImage methods. Unless otherwise specified, the size of the button is set to the size of the text, plus the padding.

tsc_ButtonControl (x_Code identifier, const tsc_Image& image);

Creates an image button control using the given image.  The image may be changed or text added with the SetImage and SetText methods. Unless otherwise specified, the size of the button is set to the image size plus the padding.

tsc_ButtonControl (x_Code identifier, const char* text, const tsc_Image& image);

Creates a button with both an image and text as supplied.  Unless otherwise specified, the button by default is sized to the image size plus the padding.

Public methods

tsc_String GetText () const;

void       SetText (const char* newText);

void       SetText(x_Code newText);

These methods get or set the text that is displayed on the button.  If the text and the image overlap, the text is drawn on top of the image.

The TextAlign and SetPadding methods may be used to control the position of the text and image within the borders of the button.

tsc_Image  GetImage ();

void       SetImage (const tsc_Image& newImage);

These methods get or set the foreground image that is displayed on the button.  The image should be a PNG file and have a transparent background so that the button's background image and/or colour will show through.

The ImageAlign and SetPadding methods may be used to control the position of the image within the borders of the button. Please note that this image is intended to be a small one accompanying the text. To create a button which is entirely made up of an image, use SetBackgroundImage instead.

In both GetImage and SetImage, the image may be a reference to the original object; images are generally not copied unless necessary.  As a consequence, changing any instance of the image may or may not be reflected in the button's appearance - unless SetImage is then called explicitly to refresh the button.

tsc_ContentAlignment TextAlign ();

void                 TextAlign (tsc_ContentAlignment textAlignment,

                                int paddingPercent = -1);

The alignment of the text within the content area can be obtained or set with these methods.  Alignment obeys the relevant edges of the rectangle formed by the supplied padding value, such that, for instance, left alignment aligns the text against the left edge and the right padding is irrelevant.  For centering, both sides are used.  The default is to center the text both horizontally and vertically. The padding is a percentage of the button's width and is the same number of pixels on all four sides.

tsc_ContentAlignment ImageAlign ();

void                 ImageAlign (tsc_ContentAlignment imageAlignment);

The alignment of the foreground image within the button's content area can be obtained or set with these methods.  Alignment occurs within the area defined by SetPadding. The default is tsc_AlignMiddleLeft. ImageAlign is only useful if the button size has been defined by SetCustomDimenions or SetBackgroundImage.

void  SetPadding  (int leftPercent,

                   int topPercent,

                   int rightPercent,

                   int bottomPercent);

Each of the four values is expressed as a percentage of the button width or height as appropriate, and must be greater than or equal to zero.

SetPadding defines a padding strip which exists like a ring around the inside of the four edges of the button and allows the image to be aligned inside this area using ImageAlign. 

In order for this to work, the button must have its size explicitly set - either by SetBackgroundImage or by SetCustomDimensions - and be at least as big as the image plus the padding thickness.

The default padding is 8% which means that the image will be placed 8% of the button's width from any side it is aligned to using ImageAlign.

If no button size has been specified then SetPadding instead computes the button size by adding the padding values to the four sides of the image. This means the inside area is exactly the size of the image so it defines the image position exactly, and ImageAlign will have no effect. Also in this case, the padding values are computed as a percentage of the image size rather than the button size.

The padding area is filled with the background color and/or the background image. If SetImage has not been called for the button, then SetPadding has no visible effect.

void SetBackgroundImage (const tsc_Image& fullImage);

Sets an image to cover the entire button, in front of the background colour but behind the foreground image and text.  Transparent parts of the background image will allow the default or specified background colors to show through for the various button states. The outermost few pixels of the background image are best left transparent, to allow the focus border to be seen.

The button will be made the same size as the specified image unless overridden by SetCustomDimensions.  Borders will not be drawn over the image; if borders are required, they must either be supplied as part of the background image or left transparent. If SetCustomDimensions specifies a button smaller than the image, the image will be shrunk to fit. If larger, the background image will occupy the upper left corner.

void SetFocusColors (const tsc_Color& foreground, const tsc_Color& background);

Sets the foreground (text) and background colours to be displayed when the button has the current focus.  Use tsc_Color::Empty() to specify the Survey Core default focus colour. 

Note that tsc_Control::SetForgroundColour and tsc_Control::SetBackgroundColour are used to set the colours displayed when the button is enabled, is not pressed, and doesn't have focus.

void SetPressedColors (const tsc_Color& foreground, const tsc_Color& background);

Sets the foreground (text) and background colours to be displayed when the button is in a depressed state.  Use tsc_Color::Empty() to specify the Survey Core default colour.

Inherited from tsc_Control

void SetForegroundColor (const tsc_Color& color);

Sets the text colour.  This colour is used when the button is in its normal state, which is when it is enabled, not depressed and does not have focus.  Also see SetFocusColors and SetPressedColors

void SetBackgroundColor (const tsc_Color& color);

Sets the background colour.   This colour is used when the button is in its normal state which is when it is enabled, not depressed and does not have focus.  Also see SetFocusColors and SetPressedColors.

Transparency and layers

The diagram below shows how the button is built up when all four components are specified.  Note that the text has been aligned BottomCentre and the small total station image aligned BottomLeft.

The diagram shows, from left to right, the order in which they are drawn from the back to the front:

• • The background colour, which is dependent on the state of the button (normal, pressed, focussed).

  • The background image, which may have transparent parts to allow the background colour to show through.

  • The button image, which may also have transparent parts, and be positioned anywhere on the button.

  • The text, which is transparent except for the characters themselves which are drawn in the foreground colour.

  • The composite result. Note the blue rectangle that occupies the outer few pixels - this is the focus rectangle which appears when the button has focus, but only if the background image has transparent pixels along its edges.