Skip to content

Commit 4da20ac

Browse files
tigtig
committed
Merged v2_develop; updated API docs
1 parent 8954fa5 commit 4da20ac

File tree

3 files changed

+459
-392
lines changed

3 files changed

+459
-392
lines changed

‎Terminal.Gui/View/Layout/ViewLayout.cs

Lines changed: 121 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -30,22 +30,31 @@ public partial class View {
3030
Rect _frame;
3131

3232
/// <summary>
33-
/// Gets or sets the frame for the view. The frame is relative to the <see cref="SuperView"/>'s <see cref="Bounds"/>.
33+
/// Gets or sets location and size of the view. The frame is relative to the <see cref="SuperView"/>'s <see cref="Bounds"/>.
3434
/// </summary>
35-
/// <value>The frame.</value>
35+
/// <value>The rectangle describing the location and size of the view, in coordinates relative to the <see cref="SuperView"/>.</value>
3636
/// <remarks>
3737
/// <para>
38-
/// Change the Frame when using the <see cref="Terminal.Gui.LayoutStyle.Absolute"/> layout style to move or resize views.
38+
/// Change the Frame when using the <see cref="LayoutStyle.Absolute"/> layout style to move or resize views.
3939
/// </para>
4040
/// <para>
41-
/// Altering the Frame of a view will trigger the redrawing of the
42-
/// view as well as the redrawing of the affected regions of the <see cref="SuperView"/>.
41+
/// Altering the Frame will change <see cref="LayoutStyle"/> to <see cref="LayoutStyle.Absolute"/>.
42+
/// Additionally, <see cref="X"/>, <see cref="Y"/>, <see cref="Width"/>, and <see cref="Height"/> will be set
43+
/// to the values of the Frame (using <see cref="Pos.PosAbsolute"/> and <see cref="Dim.DimAbsolute"/>).
44+
/// </para>
45+
/// <para>
46+
/// Altering the Frame will eventually (when the view is next drawn) cause the <see cref="LayoutSubview(View, Rect)"/>
47+
/// and <see cref="OnDrawContent(Rect)"/> methods to be called.
4348
/// </para>
4449
/// </remarks>
4550
public virtual Rect Frame {
4651
get => _frame;
4752
set {
4853
_frame = new Rect (value.X, value.Y, Math.Max (value.Width, 0), Math.Max (value.Height, 0));
54+
//X = _frame.X;
55+
//Y = _frame.Y;
56+
//Width = _frame.Width;
57+
//Height = _frame.Height;
4958
if (IsInitialized || LayoutStyle == LayoutStyle.Absolute) {
5059
LayoutFrames ();
5160
TextFormatter.Size = GetTextFormatterSizeNeededForTextAndHotKey ();
@@ -161,7 +170,7 @@ public Thickness GetFramesThickness ()
161170
/// Helper to get the X and Y offset of the Bounds from the Frame. This is the sum of the Left and Top properties of
162171
/// <see cref="Margin"/>, <see cref="Border"/> and <see cref="Padding"/>.
163172
/// </summary>
164-
public Point GetBoundsOffset () => new Point (Padding?.Thickness.GetInside (Padding.Frame).X ?? 0, Padding?.Thickness.GetInside (Padding.Frame).Y ?? 0);
173+
public Point GetBoundsOffset () => new (Padding?.Thickness.GetInside (Padding.Frame).X ?? 0, Padding?.Thickness.GetInside (Padding.Frame).Y ?? 0);
165174

166175
/// <summary>
167176
/// Creates the view's <see cref="Frame"/> objects. This internal method is overridden by Frame to do nothing
@@ -171,7 +180,9 @@ internal virtual void CreateFrames ()
171180
{
172181
void ThicknessChangedHandler (object sender, EventArgs e)
173182
{
174-
LayoutFrames ();
183+
if (IsInitialized) {
184+
LayoutFrames ();
185+
}
175186
SetNeedsLayout ();
176187
SetNeedsDisplay ();
177188
}
@@ -207,41 +218,74 @@ void ThicknessChangedHandler (object sender, EventArgs e)
207218

208219
/// <summary>
209220
/// Controls how the View's <see cref="Frame"/> is computed during <see cref="LayoutSubviews"/>. If the style is set to
210-
/// <see cref="LayoutStyle.Absolute"/>,
211-
/// LayoutSubviews does not change the <see cref="Frame"/>. If the style is <see cref="LayoutStyle.Computed"/>
212-
/// the <see cref="Frame"/> is updated using
221+
/// <see cref="LayoutStyle.Absolute"/>, LayoutSubviews does not change the <see cref="Frame"/>.
222+
/// If the style is <see cref="LayoutStyle.Computed"/> the <see cref="Frame"/> is updated using
213223
/// the <see cref="X"/>, <see cref="Y"/>, <see cref="Width"/>, and <see cref="Height"/> properties.
214224
/// </summary>
225+
/// <remarks>
226+
/// <para>
227+
/// Setting this property to <see cref="LayoutStyle.Absolute"/> will cause <see cref="Frame"/> to determine the
228+
/// size and position of the view. <see cref="X"/> and <see cref="Y"/> will be set to <see cref="Dim.DimAbsolute"/> using <see cref="Frame"/>.
229+
/// </para>
230+
/// <para>
231+
/// Setting this property to <see cref="LayoutStyle.Computed"/> will cause the view to use the <see cref="LayoutSubviews"/> method to
232+
/// size and position of the view. If either of the <see cref="X"/> and <see cref="Y"/> properties are `null` they will be set to <see cref="Pos.PosAbsolute"/> using
233+
/// the current value of <see cref="Frame"/>.
234+
/// If either of the <see cref="Width"/> and <see cref="Height"/> properties are `null` they will be set to <see cref="Dim.DimAbsolute"/> using <see cref="Frame"/>.
235+
/// </para>
236+
/// </remarks>
215237
/// <value>The layout style.</value>
216238
public LayoutStyle LayoutStyle {
217-
get => _layoutStyle;
239+
get {
240+
return _layoutStyle;
241+
//if ((X == null || X is Pos.PosAbsolute) && (Y == null || Y is Pos.PosAbsolute) &&
242+
//(Width == null || Width is Dim.DimAbsolute) && (Height == null || Height is Dim.DimAbsolute)) {
243+
// return LayoutStyle.Absolute;
244+
//} else {
245+
// return LayoutStyle.Computed;
246+
//}
247+
}
218248
set {
219249
_layoutStyle = value;
250+
//switch (_layoutStyle) {
251+
//case LayoutStyle.Absolute:
252+
// X = Frame.X;
253+
// Y = Frame.Y;
254+
// Width = Frame.Width;
255+
// Height = Frame.Height;
256+
// break;
257+
258+
//case LayoutStyle.Computed:
259+
// X ??= Frame.X;
260+
// Y ??= Frame.Y;
261+
// Width ??= Frame.Width;
262+
// Height ??= Frame.Height;
263+
// break;
264+
//}
220265
SetNeedsLayout ();
221266
}
222267
}
223268

224269
/// <summary>
225-
/// The view's content area.
226-
/// <para>
227-
/// SubViews are positioned relative to Bounds.
228-
/// </para>
270+
/// The bounds represent the View-relative rectangle used for this view; the area inside of the view where subviews and content are presented.
271+
/// </summary>
272+
/// <value>The rectangle describing the location and size of the area where the views' subviews and content are drawn.</value>
273+
/// <remarks>
229274
/// <para>
230-
/// Drawing is clipped to Bounds (<see cref="Draw()"/> clips drawing to Bounds.<see cref="Rect.Size">Size</see>).
275+
/// If <see cref="LayoutStyle"/> is <see cref="LayoutStyle.Computed"/> the value of Bounds is indeterminate until the
276+
/// view has been initialized (<see creft="IsInitialized"/> is true) and <see cref="LayoutSubviews"/> has been called.
231277
/// </para>
232278
/// <para>
233-
/// Mouse events are reported relative to Bounds.
279+
/// Updates to the Bounds updates <see cref="Frame"/>, and has the same side effects as updating the <see cref="Frame"/>.
234280
/// </para>
235-
/// </summary>
236-
/// <value>The view's content area.</value>
237-
/// <remarks>
238281
/// <para>
239-
/// The <see cref="Rect.Location"/> of Bounds is always (0, 0). To obtain the offset of the Bounds from the Frame use
240-
/// <see cref="GetBoundsOffset"/>.
282+
/// Altering the Bounds will eventually (when the view is next drawn) cause the <see cref="LayoutSubview(View, Rect)"/>
283+
/// and <see cref="OnDrawContent(Rect)"/> methods to be called.
241284
/// </para>
242285
/// <para>
243-
/// When using <see cref="LayoutStyle.Computed"/>, Bounds is not valid until after the view has been initialized (after <see cref="EndInit"/> has been called and <see cref="Initialized"/>
244-
/// has fired). Accessing this property before the view is initialized is considered an error./>
286+
/// Because <see cref="Bounds"/> coordinates are relative to the upper-left corner of the <see cref="View"/>,
287+
/// the coordinates of the upper-left corner of the rectangle returned by this property are (0,0).
288+
/// Use this property to obtain the size of the area of the view for tasks such as drawing the view's contents.
245289
/// </para>
246290
/// </remarks>
247291
public virtual Rect Bounds {
@@ -280,12 +324,21 @@ Rect FrameGetInsideBounds ()
280324
Pos _x, _y;
281325

282326
/// <summary>
283-
/// Gets or sets the X position for the view (the column). Only used if the <see cref="LayoutStyle"/> is <see cref="Terminal.Gui.LayoutStyle.Computed"/>.
327+
/// Gets or sets the X position for the view (the column).
284328
/// </summary>
285-
/// <value>The X Position.</value>
329+
/// <value>The <see cref="Pos"/> object representing the X position.</value>
286330
/// <remarks>
287331
/// <para>
288-
/// If <see cref="LayoutStyle"/> is <see cref="Terminal.Gui.LayoutStyle.Absolute"/> changing this property has no effect and its value is indeterminate.
332+
/// If <see cref="LayoutStyle"/> is <see cref="LayoutStyle.Computed"/> the value is indeterminate until the
333+
/// view has been initialized (<see creft="IsInitialized"/> is true) and <see cref="LayoutSubviews"/> has been called.
334+
/// </para>
335+
/// <para>
336+
/// Changing this property will eventually (when the view is next drawn) cause the <see cref="LayoutSubview(View, Rect)"/> and
337+
/// <see cref="OnDrawContent(Rect)"/> methods to be called.
338+
/// </para>
339+
/// <para>
340+
/// If <see cref="LayoutStyle"/> is <see cref="LayoutStyle.Absolute"/> changing this property will cause the <see cref="Frame"/> to be updated. If
341+
/// the new value is not of type <see cref="Pos.PosAbsolute"/> the <see cref="LayoutStyle"/> will change to <see cref="LayoutStyle.Computed"/>.
289342
/// </para>
290343
/// <para>
291344
/// <see langword="null"/> is the same as <c>Pos.Absolute(0)</c>.
@@ -306,14 +359,22 @@ public Pos X {
306359
}
307360
}
308361

309-
310362
/// <summary>
311-
/// Gets or sets the Y position for the view (the row). Only used if the <see cref="LayoutStyle"/> is <see cref="Terminal.Gui.LayoutStyle.Computed"/>.
363+
/// Gets or sets the Y position for the view (the row).
312364
/// </summary>
313-
/// <value>The X Position.</value>
365+
/// <value>The <see cref="Pos"/> object representing the Y position.</value>
314366
/// <remarks>
315367
/// <para>
316-
/// If <see cref="LayoutStyle"/> is <see cref="Terminal.Gui.LayoutStyle.Absolute"/> changing this property has no effect and its value is indeterminate.
368+
/// If <see cref="LayoutStyle"/> is <see cref="LayoutStyle.Computed"/> the value is indeterminate until the
369+
/// view has been initialized (<see creft="IsInitialized"/> is true) and <see cref="LayoutSubviews"/> has been called.
370+
/// </para>
371+
/// <para>
372+
/// Changing this property will eventually (when the view is next drawn) cause the <see cref="LayoutSubview(View, Rect)"/> and
373+
/// <see cref="OnDrawContent(Rect)"/> methods to be called.
374+
/// </para>
375+
/// <para>
376+
/// If <see cref="LayoutStyle"/> is <see cref="LayoutStyle.Absolute"/> changing this property will cause the <see cref="Frame"/> to be updated. If
377+
/// the new value is not of type <see cref="Pos.PosAbsolute"/> the <see cref="LayoutStyle"/> will change to <see cref="LayoutStyle.Computed"/>.
317378
/// </para>
318379
/// <para>
319380
/// <see langword="null"/> is the same as <c>Pos.Absolute(0)</c>.
@@ -333,19 +394,25 @@ public Pos Y {
333394
OnResizeNeeded ();
334395
}
335396
}
397+
336398
Dim _width, _height;
337399

338400
/// <summary>
339-
/// Gets or sets the width of the view. Only used when <see cref="LayoutStyle"/> is <see cref="Terminal.Gui.LayoutStyle.Computed"/>.
401+
/// Gets or sets the width of the view.
340402
/// </summary>
341-
/// <value>The width.</value>
403+
/// <value>The <see cref="Dim"/> object representing the width of the view (the number of columns).</value>
342404
/// <remarks>
343405
/// <para>
344-
/// If <see cref="LayoutStyle"/> is <see cref="Terminal.Gui.LayoutStyle.Absolute"/> changing this property
345-
/// has no effect and its value is indeterminate.
406+
/// If <see cref="LayoutStyle"/> is <see cref="LayoutStyle.Computed"/> the value is indeterminate until the
407+
/// view has been initialized (<see creft="IsInitialized"/> is true) and <see cref="LayoutSubviews"/> has been called.
408+
/// </para>
409+
/// <para>
410+
/// Changing this property will eventually (when the view is next drawn) cause the <see cref="LayoutSubview(View, Rect)"/>
411+
/// and <see cref="OnDrawContent(Rect)"/> methods to be called.
346412
/// </para>
347413
/// <para>
348-
/// <see langword="null"/> is the same as <c>Dim.Fill (0)</c>.
414+
/// If <see cref="LayoutStyle"/> is <see cref="LayoutStyle.Absolute"/> changing this property will cause the <see cref="Frame"/> to be updated. If
415+
/// the new value is not of type <see cref="Dim.DimAbsolute"/> the <see cref="LayoutStyle"/> will change to <see cref="LayoutStyle.Computed"/>.
349416
/// </para>
350417
/// </remarks>
351418
public Dim Width {
@@ -372,16 +439,21 @@ public Dim Width {
372439
}
373440

374441
/// <summary>
375-
/// Gets or sets the height of the view. Only used when <see cref="LayoutStyle"/> is <see cref="Terminal.Gui.LayoutStyle.Computed"/>.
442+
/// Gets or sets the height of the view.
376443
/// </summary>
377-
/// <value>The width.</value>
444+
/// <value>The <see cref="Dim"/> object representing the height of the view (the number of rows).</value>
378445
/// <remarks>
379446
/// <para>
380-
/// If <see cref="LayoutStyle"/> is <see cref="Terminal.Gui.LayoutStyle.Absolute"/> changing this property
381-
/// has no effect and its value is indeterminate.
447+
/// If <see cref="LayoutStyle"/> is <see cref="LayoutStyle.Computed"/> the value is indeterminate until the
448+
/// view has been initialized (<see creft="IsInitialized"/> is true) and <see cref="LayoutSubviews"/> has been called.
449+
/// </para>
450+
/// <para>
451+
/// Changing this property will eventually (when the view is next drawn) cause the <see cref="LayoutSubview(View, Rect)"/>
452+
/// and <see cref="OnDrawContent(Rect)"/> methods to be called.
382453
/// </para>
383454
/// <para>
384-
/// <see langword="null"/> is the same as <c>Dim.Fill (0)</c>.
455+
/// If <see cref="LayoutStyle"/> is <see cref="LayoutStyle.Absolute"/> changing this property will cause the <see cref="Frame"/> to be updated. If
456+
/// the new value is not of type <see cref="Dim.DimAbsolute"/> the <see cref="LayoutStyle"/> will change to <see cref="LayoutStyle.Computed"/>.
385457
/// </para>
386458
/// </remarks>
387459
public Dim Height {
@@ -658,7 +730,7 @@ int GetNewDimension (Dim d, int location, int dimension, int autosize)
658730
newDimension = d.Anchor (dimension);
659731
newDimension = AutoSize && autosize > newDimension ? autosize : newDimension;
660732
break;
661-
733+
662734
case Dim.DimFill:
663735
default:
664736
newDimension = Math.Max (d.Anchor (dimension - location), 0);
@@ -803,7 +875,7 @@ internal void CollectAll (View from, ref HashSet<View> nNodes, ref HashSet<(View
803875
// BUGBUG: This should really only work on initialized subviews
804876
foreach (var v in from.InternalSubviews /*.Where(v => v.IsInitialized)*/) {
805877
nNodes.Add (v);
806-
if (v._layoutStyle != LayoutStyle.Computed) {
878+
if (v.LayoutStyle != LayoutStyle.Computed) {
807879
continue;
808880
}
809881
CollectPos (v.X, v, ref nNodes, ref nEdges);
@@ -896,7 +968,6 @@ internal virtual void LayoutFrames ()
896968
Margin.Width = Frame.Size.Width;
897969
Margin.Height = Frame.Size.Height;
898970
Margin.SetNeedsLayout ();
899-
Margin.LayoutSubviews ();
900971
Margin.SetNeedsDisplay ();
901972
}
902973

@@ -908,7 +979,6 @@ internal virtual void LayoutFrames ()
908979
Border.Width = border.Size.Width;
909980
Border.Height = border.Size.Height;
910981
Border.SetNeedsLayout ();
911-
Border.LayoutSubviews ();
912982
Border.SetNeedsDisplay ();
913983
}
914984

@@ -920,7 +990,6 @@ internal virtual void LayoutFrames ()
920990
Padding.Width = padding.Size.Width;
921991
Padding.Height = padding.Size.Height;
922992
Padding.SetNeedsLayout ();
923-
Padding.LayoutSubviews ();
924993
Padding.SetNeedsDisplay ();
925994
}
926995
}
@@ -930,7 +999,13 @@ internal virtual void LayoutFrames ()
930999
/// response to the container view or terminal resizing.
9311000
/// </summary>
9321001
/// <remarks>
1002+
/// <para>
1003+
/// The position and dimensions of the view are indeterminate until the view has been initialized. Therefore,
1004+
/// the behavior of this method is indeterminate if <see cref="IsInitialized"/> is <see langword="false"/>.
1005+
/// </para>
1006+
/// <para>
9331007
/// Raises the <see cref="LayoutComplete"/> event) before it returns.
1008+
/// </para>
9341009
/// </remarks>
9351010
public virtual void LayoutSubviews ()
9361011
{

‎Terminal.Gui/View/View.cs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -238,7 +238,7 @@ void SetInitialProperties (string text, Rect rect, LayoutStyle layoutStyle = Lay
238238

239239
CreateFrames ();
240240

241-
LayoutFrames ();
241+
//LayoutFrames ();
242242
}
243243

244244
/// <summary>

0 commit comments

Comments
 (0)