| 1 | ///////////////////////////////////////////////////////////////////////////// |
| 2 | // Name: statusbr.h |
| 3 | // Purpose: interface of wxStatusBar |
| 4 | // Author: wxWidgets team |
| 5 | // RCS-ID: $Id$ |
| 6 | // Licence: wxWindows license |
| 7 | ///////////////////////////////////////////////////////////////////////////// |
| 8 | |
| 9 | /** |
| 10 | @class wxStatusBar |
| 11 | |
| 12 | A status bar is a narrow window that can be placed along the bottom of a frame |
| 13 | to give small amounts of status information. It can contain one or more fields, |
| 14 | one or more of which can be variable length according to the size of the window. |
| 15 | |
| 16 | @beginStyleTable |
| 17 | @style{wxST_SIZEGRIP} |
| 18 | On Windows 95, displays a gripper at right-hand side of the status bar. |
| 19 | @endStyleTable |
| 20 | |
| 21 | @todo reference to win95 may be old and wrong |
| 22 | |
| 23 | @remarks |
| 24 | It is possible to create controls and other windows on the status bar. |
| 25 | Position these windows from an OnSize event handler. |
| 26 | |
| 27 | @library{wxcore} |
| 28 | @category{miscwnd} |
| 29 | |
| 30 | @see wxFrame, @ref page_samples_statbar |
| 31 | */ |
| 32 | class wxStatusBar : public wxWindow |
| 33 | { |
| 34 | public: |
| 35 | /** |
| 36 | Default ctor. |
| 37 | */ |
| 38 | wxStatusBar(); |
| 39 | |
| 40 | /** |
| 41 | Constructor, creating the window. |
| 42 | |
| 43 | @param parent |
| 44 | The window parent, usually a frame. |
| 45 | @param id |
| 46 | The window identifier. |
| 47 | It may take a value of -1 to indicate a default value. |
| 48 | @param style |
| 49 | The window style. See wxStatusBar. |
| 50 | @param name |
| 51 | The name of the window. This parameter is used to associate a name with the |
| 52 | item, allowing the application user to set Motif resource values for |
| 53 | individual windows. |
| 54 | |
| 55 | @see Create() |
| 56 | */ |
| 57 | wxStatusBar(wxWindow* parent, wxWindowID id = wxID_ANY, |
| 58 | long style = wxST_SIZEGRIP, |
| 59 | const wxString& name = "statusBar"); |
| 60 | |
| 61 | /** |
| 62 | Destructor. |
| 63 | */ |
| 64 | virtual ~wxStatusBar(); |
| 65 | |
| 66 | /** |
| 67 | Creates the window, for two-step construction. |
| 68 | See wxStatusBar() for details. |
| 69 | */ |
| 70 | bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, |
| 71 | long style = wxST_SIZEGRIP, |
| 72 | const wxString& name = "statusBar"); |
| 73 | |
| 74 | /** |
| 75 | Returns the size and position of a field's internal bounding rectangle. |
| 76 | |
| 77 | @param i |
| 78 | The field in question. |
| 79 | @param rect |
| 80 | The rectangle values are placed in this variable. |
| 81 | |
| 82 | @return @true if the field index is valid, @false otherwise. |
| 83 | |
| 84 | @see wxRect |
| 85 | */ |
| 86 | virtual bool GetFieldRect(int i, wxRect& rect) const; |
| 87 | |
| 88 | /** |
| 89 | Returns the number of fields in the status bar. |
| 90 | */ |
| 91 | int GetFieldsCount() const; |
| 92 | |
| 93 | /** |
| 94 | Returns the string associated with a status bar field. |
| 95 | |
| 96 | @param i |
| 97 | The number of the status field to retrieve, starting from zero. |
| 98 | |
| 99 | @return The status field string if the field is valid, otherwise the |
| 100 | empty string. |
| 101 | |
| 102 | @see SetStatusText() |
| 103 | */ |
| 104 | virtual wxString GetStatusText(int i = 0) const; |
| 105 | |
| 106 | /** |
| 107 | Sets the field text to the top of the stack, and pops the stack of saved |
| 108 | strings. |
| 109 | |
| 110 | @see PushStatusText() |
| 111 | */ |
| 112 | void PopStatusText(int field = 0); |
| 113 | |
| 114 | /** |
| 115 | Saves the current field text in a per field stack, and sets the field text |
| 116 | to the string passed as argument. |
| 117 | */ |
| 118 | void PushStatusText(const wxString& string, int field = 0); |
| 119 | |
| 120 | /** |
| 121 | Sets the number of fields, and optionally the field widths. |
| 122 | |
| 123 | @param number |
| 124 | The number of fields. |
| 125 | @param widths |
| 126 | An array of n integers interpreted in the same way as |
| 127 | in SetStatusWidths(). |
| 128 | */ |
| 129 | virtual void SetFieldsCount(int number = 1, int* widths = NULL); |
| 130 | |
| 131 | /** |
| 132 | Sets the minimal possible height for the status bar. |
| 133 | |
| 134 | The real height may be bigger than the height specified here depending |
| 135 | on the size of the font used by the status bar. |
| 136 | */ |
| 137 | virtual void SetMinHeight(int height); |
| 138 | |
| 139 | /** |
| 140 | Sets the styles of the fields in the status line which can make fields appear |
| 141 | flat or raised instead of the standard sunken 3D border. |
| 142 | |
| 143 | @param n |
| 144 | The number of fields in the status bar. Must be equal to the |
| 145 | number passed to SetFieldsCount() the last time it was called. |
| 146 | @param styles |
| 147 | Contains an array of n integers with the styles for each field. There |
| 148 | are three possible styles: |
| 149 | - wxSB_NORMAL (default): The field appears sunken with a standard 3D border. |
| 150 | - wxSB_FLAT: No border is painted around the field so that it appears flat. |
| 151 | - wxSB_RAISED: A raised 3D border is painted around the field. |
| 152 | */ |
| 153 | virtual void SetStatusStyles(int n, int* styles); |
| 154 | |
| 155 | /** |
| 156 | Sets the text for one field. |
| 157 | |
| 158 | @param text |
| 159 | The text to be set. Use an empty string ("") to clear the field. |
| 160 | @param i |
| 161 | The field to set, starting from zero. |
| 162 | |
| 163 | @see GetStatusText(), wxFrame::SetStatusText |
| 164 | */ |
| 165 | virtual void SetStatusText(const wxString& text, int i = 0); |
| 166 | |
| 167 | /** |
| 168 | Sets the widths of the fields in the status line. There are two types of |
| 169 | fields: fixed widths one and variable width fields. For the fixed width fields |
| 170 | you should specify their (constant) width in pixels. For the variable width |
| 171 | fields, specify a negative number which indicates how the field should expand: |
| 172 | the space left for all variable width fields is divided between them according |
| 173 | to the absolute value of this number. A variable width field with width of -2 |
| 174 | gets twice as much of it as a field with width -1 and so on. |
| 175 | |
| 176 | For example, to create one fixed width field of width 100 in the right part of |
| 177 | the status bar and two more fields which get 66% and 33% of the remaining |
| 178 | space correspondingly, you should use an array containing -2, -1 and 100. |
| 179 | |
| 180 | @param n |
| 181 | The number of fields in the status bar. Must be equal to the |
| 182 | number passed to SetFieldsCount() the last time it was called. |
| 183 | @param widths |
| 184 | Contains an array of n integers, each of which is either an |
| 185 | absolute status field width in pixels if positive or indicates a |
| 186 | variable width field if negative. |
| 187 | |
| 188 | @remarks The widths of the variable fields are calculated from the total |
| 189 | width of all fields, minus the sum of widths of the |
| 190 | non-variable fields, divided by the number of variable fields. |
| 191 | |
| 192 | @see SetFieldsCount(), wxFrame::SetStatusWidths() |
| 193 | */ |
| 194 | virtual void SetStatusWidths(int n, int* widths); |
| 195 | }; |
| 196 | |