• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
4 
5 #ifndef UI_VIEWS_LAYOUT_GRID_LAYOUT_H_
6 #define UI_VIEWS_LAYOUT_GRID_LAYOUT_H_
7 
8 #include <string>
9 #include <vector>
10 
11 #include "base/compiler_specific.h"
12 #include "ui/gfx/insets.h"
13 #include "ui/views/layout/layout_manager.h"
14 #include "ui/views/view.h"
15 
16 // GridLayout is a LayoutManager that positions child Views in a grid. You
17 // define the structure of the Grid first, then add the Views.
18 // The following creates a trivial grid with two columns separated by
19 // a column with padding:
20 // ColumnSet* columns = layout->AddColumnSet(0); // Give this column an
21 //                                               // identifier of 0.
22 // columns->AddColumn(FILL, // Views are horizontally resized to fill column.
23 //                    FILL, // Views starting in this column are vertically
24 //                          // resized.
25 //                    1,    // This column has a resize weight of 1.
26 //                    USE_PREF, // Use the preferred size of the view.
27 //                    0,   // Ignored for USE_PREF.
28 //                    0);  // A minimum width of 0.
29 // columns->AddPaddingColumn(0,   // The padding column is not resizable.
30 //                           10); // And has a width of 10 pixels.
31 // columns->AddColumn(FILL, FILL, 0, USE_PREF, 0, 0);
32 // Now add the views:
33 // // First start a row.
34 // layout->StartRow(0,  // This row isn't vertically resizable.
35 //                  0); // The column set to use for this row.
36 // layout->AddView(v1);
37 // Notice you need not skip over padding columns, that's done for you.
38 // layout->AddView(v2);
39 //
40 // When adding a Column you give it the default alignment for all views
41 // originating in that column. You can override this for specific views
42 // when adding them. For example, the following forces a View to have
43 // a horizontal and vertical alignment of leading regardless of that defined
44 // for the column:
45 // layout->AddView(v1, 1, 1, LEADING, LEADING);
46 //
47 // If the View using GridLayout is given a size bigger than the preferred,
48 // columns and rows with a resize percent > 0 are resized. Each column/row
49 // is given resize_percent / total_resize_percent * extra_pixels extra
50 // pixels. Only Views with an Alignment of FILL are given extra space, others
51 // are aligned in the provided space.
52 //
53 // GridLayout allows you to define multiple column sets. When you start a
54 // new row you specify the id of the column set the row is to use.
55 //
56 // GridLayout allows you to force columns to have the same width. This is
57 // done using the LinkColumnSizes method.
58 //
59 // AddView takes care of adding the View to the View the GridLayout was
60 // created with.
61 namespace views {
62 
63 class Column;
64 class ColumnSet;
65 class Row;
66 class View;
67 
68 struct ViewState;
69 
70 class VIEWS_EXPORT GridLayout : public LayoutManager {
71  public:
72   // An enumeration of the possible alignments supported by GridLayout.
73   enum Alignment {
74     // Leading equates to left along the horizontal axis, and top along the
75     // vertical axis.
76     LEADING,
77 
78     // Centers the view along the axis.
79     CENTER,
80 
81     // Trailing equals to right along the horizontal axis, and bottom along
82     // the vertical axis.
83     TRAILING,
84 
85     // The view is resized to fill the space.
86     FILL,
87 
88     // The view is aligned along the baseline. This is only valid for the
89     // vertical axis.
90     BASELINE
91   };
92 
93   // An enumeration of the possible ways the size of a column may be obtained.
94   enum SizeType {
95     // The column size is fixed.
96     FIXED,
97 
98     // The preferred size of the view is used to determine the column size.
99     USE_PREF
100   };
101 
102   explicit GridLayout(View* host);
103   virtual ~GridLayout();
104 
105   // Creates a GridLayout with kPanel*Margin insets.
106   static GridLayout* CreatePanel(View* host);
107 
108   // Sets the insets. All views are placed relative to these offsets.
109   void SetInsets(int top, int left, int bottom, int right);
110   void SetInsets(const gfx::Insets& insets);
111 
112   // Creates a new column set with the specified id and returns it.
113   // The id is later used when starting a new row.
114   // GridLayout takes ownership of the ColumnSet and will delete it when
115   // the GridLayout is deleted.
116   ColumnSet* AddColumnSet(int id);
117 
118   // Returns the column set for the specified id, or NULL if one doesn't exist.
119   ColumnSet* GetColumnSet(int id);
120 
121   // Adds a padding row. Padding rows typically don't have any views, and
122   // but are used to provide vertical white space between views.
123   // Size specifies the height of the row.
124   void AddPaddingRow(float vertical_resize, int size);
125 
126   // A convenience for AddPaddingRow followed by StartRow.
127   void StartRowWithPadding(float vertical_resize, int column_set_id,
128                            float padding_resize, int padding);
129 
130   // Starts a new row with the specified column set.
131   void StartRow(float vertical_resize, int column_set_id);
132 
133   // Advances past columns. Use this when the current column should not
134   // contain any views.
135   void SkipColumns(int col_count);
136 
137   // Adds a view using the default alignment from the column. The added
138   // view has a column and row span of 1.
139   // As a convenience this adds the view to the host. The view becomes owned
140   // by the host, and NOT this GridLayout.
141   void AddView(View* view);
142 
143   // Adds a view using the default alignment from the column.
144   // As a convenience this adds the view to the host. The view becomes owned
145   // by the host, and NOT this GridLayout.
146   void AddView(View* view, int col_span, int row_span);
147 
148   // Adds a view with the specified alignment and spans.
149   // As a convenience this adds the view to the host. The view becomes owned
150   // by the host, and NOT this GridLayout.
151   void AddView(View* view, int col_span, int row_span, Alignment h_align,
152                Alignment v_align);
153 
154   // Adds a view with the specified alignment and spans. If
155   // pref_width/pref_height is > 0 then the preferred width/height of the view
156   // is fixed to the specified value.
157   // As a convenience this adds the view to the host. The view becomes owned
158   // by the host, and NOT this GridLayout.
159   void AddView(View* view, int col_span, int row_span,
160                Alignment h_align, Alignment v_align,
161                int pref_width, int pref_height);
162 
163   // Notification we've been installed on a particular host. Checks that host
164   // is the same as the View supplied in the constructor.
165   virtual void Installed(View* host) OVERRIDE;
166 
167   // Notification we've been uninstalled on a particular host. Checks that host
168   // is the same as the View supplied in the constructor.
169   virtual void Uninstalled(View* host) OVERRIDE;
170 
171   // Notification that a view has been added.
172   virtual void ViewAdded(View* host, View* view) OVERRIDE;
173 
174   // Notification that a view has been removed.
175   virtual void ViewRemoved(View* host, View* view) OVERRIDE;
176 
177   // Layouts out the components.
178   virtual void Layout(View* host) OVERRIDE;
179 
180   // Returns the preferred size for the GridLayout.
181   virtual gfx::Size GetPreferredSize(View* host) OVERRIDE;
182 
183   virtual int GetPreferredHeightForWidth(View* host, int width) OVERRIDE;
184 
set_minimum_size(const gfx::Size & size)185   void set_minimum_size(const gfx::Size& size) { minimum_size_ = size; }
186 
187  private:
188   // As both Layout and GetPreferredSize need to do nearly the same thing,
189   // they both call into this method. This sizes the Columns/Rows as
190   // appropriate. If layout is true, width/height give the width/height the
191   // of the host, otherwise they are ignored.
192   void SizeRowsAndColumns(bool layout, int width, int height, gfx::Size* pref);
193 
194   // Calculates the master columns of all the column sets. See Column for
195   // a description of what a master column is.
196   void CalculateMasterColumnsIfNecessary();
197 
198   // This is called internally from AddView. It adds the ViewState to the
199   // appropriate structures, and updates internal fields such as next_column_.
200   void AddViewState(ViewState* view_state);
201 
202   // Adds the Row to rows_, as well as updating next_column_,
203   // current_row_col_set ...
204   void AddRow(Row* row);
205 
206   // As the name says, updates the remaining_height of the ViewState for
207   // all Rows the supplied ViewState touches.
208   void UpdateRemainingHeightFromRows(ViewState* state);
209 
210   // If the view state's remaining height is > 0, it is distributed among
211   // the rows the view state touches. This is used during layout to make
212   // sure the Rows can accommodate a view.
213   void DistributeRemainingHeight(ViewState* state);
214 
215   // Advances next_column_ past any padding columns.
216   void SkipPaddingColumns();
217 
218   // Returns the column set of the last non-padding row.
219   ColumnSet* GetLastValidColumnSet();
220 
221   // The view we were created with. We don't own this.
222   View* const host_;
223 
224   // Whether or not we've calculated the master/linked columns.
225   bool calculated_master_columns_;
226 
227   // Used to verify a view isn't added with a row span that expands into
228   // another column structure.
229   int remaining_row_span_;
230 
231   // Current row.
232   int current_row_;
233 
234   // Current column.
235   int next_column_;
236 
237   // Column set for the current row. This is null for padding rows.
238   ColumnSet* current_row_col_set_;
239 
240   // Insets.
241   gfx::Insets insets_;
242 
243   // Set to true when adding a View.
244   bool adding_view_;
245 
246   // ViewStates. This is ordered by row_span in ascending order.
247   std::vector<ViewState*> view_states_;
248 
249   // ColumnSets.
250   std::vector<ColumnSet*> column_sets_;
251 
252   // Rows.
253   std::vector<Row*> rows_;
254 
255   // Minimum preferred size.
256   gfx::Size minimum_size_;
257 
258   DISALLOW_COPY_AND_ASSIGN(GridLayout);
259 };
260 
261 // ColumnSet is used to define a set of columns. GridLayout may have any
262 // number of ColumnSets. You don't create a ColumnSet directly, instead
263 // use the AddColumnSet method of GridLayout.
264 class VIEWS_EXPORT ColumnSet {
265  public:
266   ~ColumnSet();
267 
268   // Adds a column for padding. When adding views, padding columns are
269   // automatically skipped. For example, if you create a column set with
270   // two columns separated by a padding column, the first AddView automatically
271   // skips past the padding column. That is, to add two views, do:
272   // layout->AddView(v1); layout->AddView(v2);, not:
273   // layout->AddView(v1); layout->SkipColumns(1); layout->AddView(v2);
274   void AddPaddingColumn(float resize_percent, int width);
275 
276   // Adds a column. The alignment gives the default alignment for views added
277   // with no explicit alignment. fixed_width gives a specific width for the
278   // column, and is only used if size_type == FIXED. min_width gives the
279   // minimum width for the column.
280   //
281   // If none of the columns in a columnset are resizable, the views are only
282   // made as wide as the widest views in each column, even if extra space is
283   // provided. In other words, GridLayout does not automatically resize views
284   // unless the column is marked as resizable.
285   void AddColumn(GridLayout::Alignment h_align,
286                  GridLayout::Alignment v_align,
287                  float resize_percent,
288                  GridLayout::SizeType size_type,
289                  int fixed_width,
290                  int min_width);
291 
292   // Forces the specified columns to have the same size. The size of
293   // linked columns is that of the max of the specified columns. This
294   // must end with -1. For example, the following forces the first and
295   // second column to have the same size:
296   // LinkColumnSizes(0, 1, -1);
297   void LinkColumnSizes(int first, ...);
298 
299   // ID of this ColumnSet.
id()300   int id() const { return id_; }
301 
num_columns()302   int num_columns() const { return static_cast<int>(columns_.size()); }
303 
304  private:
305   friend class GridLayout;
306 
307   explicit ColumnSet(int id);
308 
309   void AddColumn(GridLayout::Alignment h_align,
310                  GridLayout::Alignment v_align,
311                  float resize_percent,
312                  GridLayout::SizeType size_type,
313                  int fixed_width,
314                  int min_width,
315                  bool is_padding);
316 
317   void AddViewState(ViewState* view_state);
318 
319   // Set description of these.
320   void CalculateMasterColumns();
321   void AccumulateMasterColumns();
322 
323   // Sets the size of each linked column to be the same.
324   void UnifySameSizedColumnSizes();
325 
326   // Updates the remaining width field of the ViewState from that of the
327   // columns the view spans.
328   void UpdateRemainingWidth(ViewState* view_state);
329 
330   // Makes sure the columns touched by view state are big enough for the
331   // view.
332   void DistributeRemainingWidth(ViewState* view_state);
333 
334   // Returns the total size needed for this ColumnSet.
335   int LayoutWidth();
336 
337   // Returns the width of the specified columns.
338   int GetColumnWidth(int start_col, int col_span);
339 
340   // Updates the x coordinate of each column from the previous ones.
341   // NOTE: this doesn't include the insets.
342   void ResetColumnXCoordinates();
343 
344   // Calculate the preferred width of each view in this column set, as well
345   // as updating the remaining_width.
346   void CalculateSize();
347 
348   // Distributes delta amoung the resizable columns.
349   void Resize(int delta);
350 
351   // ID for this columnset.
352   const int id_;
353 
354   // The columns.
355   std::vector<Column*> columns_;
356 
357   // The ViewStates. This is sorted based on column_span in ascending
358   // order.
359   std::vector<ViewState*> view_states_;
360 
361   // The master column of those columns that are linked. See Column
362   // for a description of what the master column is.
363   std::vector<Column*> master_columns_;
364 
365   DISALLOW_COPY_AND_ASSIGN(ColumnSet);
366 };
367 
368 }  // namespace views
369 
370 #endif  // UI_VIEWS_LAYOUT_GRID_LAYOUT_H_
371