<?xml version="1.0" encoding="UTF-8"?>
<fpdoc-descriptions>
  <package name="LazControls">

    <module name="ExtendedNotebook">
      <short>
        Contains an extended notebook  with support for dragging and dropping tabs on the control.
      </short>
      <descr>
        <p>
          <file>ExtendedNotebook.pas</file> contains classes and types used to implement an extended notebook control. It provides support for dragging and dropping tabs on the control.
        </p>
        <p>
          This file is part of the <file>LazControls</file> package,
        </p>
      </descr>

      <!-- unresolved external references -->
      <element name="Classes"/>
      <element name="SysUtils"/>
      <element name="Math"/>
      <element name="LCLIntf"/>
      <element name="LCLType"/>
      <element name="LMessages"/>
      <element name="Controls"/>
      <element name="ComCtrls"/>
      <element name="LCLProc"/>

      <element name="TNotebookTabDragDropEvent">
        <short>
          Specifies an event handler signalled for a drag/drop event on a notebook tab.
        </short>
        <descr>
          <p>
            TNotebookTabDragDropEvent is the type used for the OnTabDragDropEx property in TExtendedNotebook. It is used to perform actions needed when a tab on a TExtendedNotebook control is moved to a new location using drag and drop.
          </p>
          <p>
            An application must implement and assign an object method which uses this signature to respond to the event notification. It is signalled from the DragDrop method in TExtendedNotebook, and occurs after its OnTabDragOverEx event.
          </p>
        </descr>
        <seealso>
          <link id="TExtendedNotebook.OnTabDragDropEx"/>
          <link id="TExtendedNotebook.OnTabDragOverEx"/>
          <link id="TExtendedNotebook.DragDrop"/>
        </seealso>
      </element>
      <element name="TNotebookTabDragDropEvent.Sender">
        <short>Object for the notification.</short>
      </element>
      <element name="TNotebookTabDragDropEvent.Source">
        <short>Control where the drag operation originated.</short>
      </element>
      <element name="TNotebookTabDragDropEvent.OldIndex">
        <short>Original ordinal position for the dragged tab.</short>
      </element>
      <element name="TNotebookTabDragDropEvent.NewIndex">
        <short>New ordinal position for the dragged tab.</short>
      </element>
      <element name="TNotebookTabDragDropEvent.CopyDrag">
        <short>True if the Ctrl key is pressed during the drag and drop operation.</short>
      </element>
      <element name="TNotebookTabDragDropEvent.Done">
        <short>True if the tab can be moved to the new location.</short>
      </element>

      <element name="TNotebookTabDragOverEvent">
        <short>
          Specifies an event handler signalled when a dragged tab is over a notebook control.
        </short>
        <descr/>
        <seealso>
          <link id="TExtendedNotebook.OnTabDragOverEx"/>
          <link id="TExtendedNotebook.OnTabDragOver"/>
          <link id="TExtendedNotebook.DragOver"/>
        </seealso>
      </element>
      <element name="TNotebookTabDragOverEvent.Sender">
        <short>Object for the notification.</short>
      </element>
      <element name="TNotebookTabDragOverEvent.Source">
        <short>Control where the drag operation originated.</short>
      </element>
      <element name="TNotebookTabDragOverEvent.OldIndex">
        <short>Original ordinal position for the dragged tab.</short>
      </element>
      <element name="TNotebookTabDragOverEvent.NewIndex">
        <short>New ordinal position for the dragged tab.</short>
      </element>
      <element name="TNotebookTabDragOverEvent.CopyDrag">
        <short>True if the Ctrl key is pressed during the drag and drop operation.</short>
      </element>
      <element name="TNotebookTabDragOverEvent.Accept">
        <short>True if the notebook control can accept the dragged tab.</short>
      </element>

      <element name="TExtendedNotebook">
        <short>
          Implements a notebook or page control which supports drag and drop events for its tabs.
        </short>
        <descr>
          <p>
            TExtendedNotebook is a TPageControl descendant, and extends the ancestor class with properties, methods, and events which enable drag and drop operations for the tabs on the paged notebook control. It works in conjunction with the DragManager (TDragManager) instance for the LCL interface.
          </p>
          <p>
            Overridden methods are provided initiates and completes a drag and drop operation, as well as handle mouse up, down and move messages for the control. Event handlers signalled during drag and drop are also provided. Additional properties are introduced to indicate how drop / drop operations are handled by the control and to identify the tab affected by the operation.
          </p>
          <p>
            TExtendedNotebook is used in the implementation of TSourceWindow in the Lazarus IDE, where it provides access to the source editor for a tab, as well as its form and anchor design surfaces.
          </p>
        </descr>
        <seealso>
          <link id="#lcl.comctrls.TPageControl">TPageControl</link>
          <link id="#lcl.controls.TDragManager">TDragManager</link>
          <link id="#lcl.controls.DragManager">DragManager</link>
        </seealso>
      </element>

      <!-- private  -->
      <element name="TExtendedNotebook.FDraggingTabIndex"/>
      <element name="TExtendedNotebook.FOnTabDragDrop"/>
      <element name="TExtendedNotebook.FOnTabDragOver"/>
      <element name="TExtendedNotebook.FOnTabDragOverEx"/>
      <element name="TExtendedNotebook.FOnTabDragDropEx"/>
      <element name="TExtendedNotebook.FOnTabEndDrag"/>
      <element name="TExtendedNotebook.FOnTabStartDrag"/>
      <element name="TExtendedNotebook.FTabDragMode"/>
      <element name="TExtendedNotebook.FTabDragAcceptMode"/>
      <element name="TExtendedNotebook.FTabDragged"/>
      <element name="TExtendedNotebook.FDragOverIndex"/>
      <element name="TExtendedNotebook.FDragToRightSide"/>
      <element name="TExtendedNotebook.FDragOverTabRect"/>
      <element name="TExtendedNotebook.FDragNextToTabRect"/>
      <element name="TExtendedNotebook.FMouseWaitForDrag"/>
      <element name="TExtendedNotebook.FMouseDownIndex"/>
      <element name="TExtendedNotebook.FMouseDownX"/>
      <element name="TExtendedNotebook.FMouseDownY"/>
      <element name="TExtendedNotebook.FTriggerDragX"/>
      <element name="TExtendedNotebook.FTriggerDragY"/>

      <element name="TExtendedNotebook.InitDrag"/>

      <element name="TExtendedNotebook.InvalidateRect"/>
      <element name="TExtendedNotebook.InvalidateRect.ARect"/>

      <element name="TExtendedNotebook.TabIndexForDrag"/>
      <element name="TExtendedNotebook.TabIndexForDrag.Result"/>
      <element name="TExtendedNotebook.TabIndexForDrag.x"/>
      <element name="TExtendedNotebook.TabIndexForDrag.y"/>

      <element name="TExtendedNotebook.TabRectEx"/>
      <element name="TExtendedNotebook.TabRectEx.Result"/>
      <element name="TExtendedNotebook.TabRectEx.AIndex"/>
      <element name="TExtendedNotebook.TabRectEx.X"/>
      <element name="TExtendedNotebook.TabRectEx.Y"/>
      <element name="TExtendedNotebook.TabRectEx.IsRightHalf"/>

      <element name="TExtendedNotebook.MouseDown">
        <short>Handles mouse down messages for the control.</short>
        <descr>
          <p>
            MouseDown is an overridden method in TExtendedNotebook. It initializes members used to track drag and drop operations in the class instance, and sets the DragCursor for the control. It calls the inherited MouseDown method to handle an OnEditingDone event for the ActiveControl on the parent form. It updates DragManager for the mouse button in the notification, and signals the OnMouseDown event handler (when assigned). When DragMode is set to dmAutomatic, a left mouse button event causes the value in MouseCapture to be set to True.
          </p>
          <p>
            MouseDown is called from methods which process LM_LBUTTONDOWN, LM_RBUTTONDOWN, LM_MBUTTONDOWN, and LM_XBUTTONDOWN window messages for the control.
          </p>
        </descr>
        <seealso>
          <link id="#lcl.controls.TControl.OnEditingDone">TControl.OnEditingDone</link>
          <link id="#lcl.controls.TControl.MouseDown">TControl.MouseDown</link>
          <link id="#lcl.controls.TControl.WMLButtonDown">TControl.WMLButtonDown</link>
          <link id="#lcl.controls.TControl.WMRButtonDown">TControl.WMRButtonDown</link>
          <link id="#lcl.controls.TControl.WMMButtonDown">TControl.WMMButtonDown</link>
          <link id="#lcl.controls.TControl.WMXButtonDown">TControl.WMXButtonDown</link>
        </seealso>
      </element>
      <element name="TExtendedNotebook.MouseDown.Button">
        <short>Mouse button for the event.</short>
      </element>
      <element name="TExtendedNotebook.MouseDown.Shift">
        <short>Shift, Ctrl, or Alt modifier for the mouse button event.</short>
      </element>
      <element name="TExtendedNotebook.MouseDown.X">
        <short>Horizontal coordinate for the mouse pointer.</short>
      </element>
      <element name="TExtendedNotebook.MouseDown.Y">
        <short>Vertical  coordinate for the mouse pointer.</short>
      </element>

      <element name="TExtendedNotebook.MouseUp">
        <short>Handles mouse up events for the control.</short>
        <descr/>
        <seealso/>
      </element>
      <element name="TExtendedNotebook.MouseUp.Button">
        <short>Mouse button for the event.</short>
      </element>
      <element name="TExtendedNotebook.MouseUp.Shift">
        <short>Shift, Ctrl, or Alt modifier for the mouse button event.</short>
      </element>
      <element name="TExtendedNotebook.MouseUp.X">
        <short>Horizontal coordinate for the mouse pointer.</short>
      </element>
      <element name="TExtendedNotebook.MouseUp.Y">
        <short>Vertical  coordinate for the mouse pointer.</short>
      </element>

      <element name="TExtendedNotebook.MouseMove">
        <short>Handles mouse move messages for the control.</short>
        <descr/>
        <seealso/>
      </element>
      <element name="TExtendedNotebook.MouseMove.Shift">
        <short>Shift, Ctrl, or Alt modifier for the mouse button event.</short>
      </element>
      <element name="TExtendedNotebook.MouseMove.X">
        <short>Horizontal coordinate for the mouse pointer.</short>
      </element>
      <element name="TExtendedNotebook.MouseMove.Y">
        <short>Vertical  coordinate for the mouse pointer.</short>
      </element>

      <element name="TExtendedNotebook.CNNotify">
        <short>Handles control notification messages for the control.</short>
        <descr/>
        <seealso/>
      </element>
      <element name="TExtendedNotebook.CNNotify.Message">
        <short>Message examined in the method.</short>
      </element>

      <element name="TExtendedNotebook.RemovePage">
        <short>Removes the page at the specified ordinal position.</short>
        <descr/>
        <seealso/>
      </element>
      <element name="TExtendedNotebook.RemovePage.Index">
        <short>Ordinal position for the page removed in the method.</short>
      </element>

      <element name="TExtendedNotebook.InsertPage">
        <short>Inserts the specified page at the ordinal position in Index.</short>
        <descr/>
        <seealso/>
      </element>
      <element name="TExtendedNotebook.InsertPage.APage">
        <short>Page instance inserted in the method.</short>
      </element>
      <element name="TExtendedNotebook.InsertPage.Index">
        <short>Ordinal position where the page instance is inserted.</short>
      </element>

      <element name="TExtendedNotebook.CaptureChanged">
        <short>Performs actions when the mouse capture has changed for the control.</short>
        <descr/>
        <seealso/>
      </element>

      <element name="TExtendedNotebook.DoStartDrag">
        <short>Performs actions needed when a drag operation is started for the control.</short>
        <descr/>
        <seealso/>
      </element>
      <element name="TExtendedNotebook.DoStartDrag.DragObject">
        <short>Object which is dragged in the operation.</short>
      </element>

      <element name="TExtendedNotebook.DoEndDrag">
        <short>Performs actions needed when a drag operation is ended for the control.</short>
        <descr/>
        <seealso/>
      </element>
      <element name="TExtendedNotebook.DoEndDrag.Target">
        <short>Target for the drag operation.</short>
      </element>
      <element name="TExtendedNotebook.DoEndDrag.X">
        <short>Horizontal coordinate where the drag operation was ended.</short>
      </element>
      <element name="TExtendedNotebook.DoEndDrag.Y">
        <short>Vertical coordinate where the drag operation was ended.</short>
      </element>

      <element name="TExtendedNotebook.DragOver">
        <short>
          Performs actions needed when a drag operation is over a tab on the control.
        </short>
        <descr/>
        <seealso/>
      </element>
      <element name="TExtendedNotebook.DragOver.Source">
        <short/>
      </element>
      <element name="TExtendedNotebook.DragOver.X">
        <short/>
      </element>
      <element name="TExtendedNotebook.DragOver.Y">
        <short/>
      </element>
      <element name="TExtendedNotebook.DragOver.State">
        <short/>
      </element>
      <element name="TExtendedNotebook.DragOver.Accept">
        <short/>
      </element>

      <element name="TExtendedNotebook.DragCanceled">
        <short>Performs actions needed to cancel a drag operation for the control.</short>
        <descr/>
        <seealso/>
      </element>

      <element name="TExtendedNotebook.PaintWindow">
        <short>Paints the window for the control to the specified device context.</short>
        <descr/>
        <seealso>
          <link id="#lcl.controls.TWinControl.PaintWindow">TWinControl.PaintWindow</link>
          <link id="#lcl.comctrls.TPageControl.TabPosition">TPageControl.TabPosition</link>
        </seealso>
      </element>
      <element name="TExtendedNotebook.PaintWindow.DC">
        <short>Device context where the window is drawn.</short>
      </element>

      <element name="TExtendedNotebook.Create">
        <short>Constructor for the class instance.</short>
        <descr>
          <p>
            <var>Create</var> is the overridden constructor for the class instance. It ensures that internal members used in drag and drop operations are initialized for the class instance.
          </p>
        </descr>
        <seealso>
          <link id="TExtendedNotebook.TabDragMode"/>
          <link id="#lcl.comctrls.TPageControl.DragCursor">TPageControl.DragCursor</link>
        </seealso>
      </element>
      <element name="TExtendedNotebook.Create.TheOwner">
        <short>Owner of the class instance.</short>
      </element>

      <element name="TExtendedNotebook.DragDrop">
        <short>
          Performs actions needed when a dragged object is dropped onto the control.
        </short>
        <descr>
          <p>
            <var>DragDrop</var> is an overridden method in <var>TExtendedNotebook</var> used to perform actions needed when the object in <var>Source</var> is dropped on the control.
          </p>
          <p>
            If Source is not derived from TExtendedNotebook, or not the tab being dragged in the control, the inherited method is called to signal the OnDragDrop event handler (when assigned). No additional actions are performed in the method when this situation occurs.
          </p>
          <p>
            The OnTabDragDrop event handler is signalled (when assigned) for the TExtendedNotebook instance in Source. The OnTabDragDropEx event handler is signalled (when assigned) to allow Ctrl + Drag mouse messages to be handled for the control.
          </p>
          <p>
            If the tab order was changed by the drag operation, the tabs (pages) are re-ordered to reflect the new position.
          </p>
        </descr>
        <seealso/>
      </element>
      <element name="TExtendedNotebook.DragDrop.Source">
        <short>Object dragged / dropped on to the control.</short>
      </element>
      <element name="TExtendedNotebook.DragDrop.X">
        <short>Horizontal coordinate where the drop occurred.</short>
      </element>
      <element name="TExtendedNotebook.DragDrop.Y">
        <short>Vertical coordinate where the drop occurred.</short>
      </element>

      <element name="TExtendedNotebook.BeginDragTab">
        <short>Starts a drag operation for a tab on the control.</short>
        <descr>
          <p>
            Called from the MouseMove method when a mouse down event has occurred on a tab in the control.
          </p>
        </descr>
        <seealso/>
      </element>
      <element name="TExtendedNotebook.BeginDragTab.ATabIndex">
        <short>Ordinal position for the tab affected in the drag operation.</short>
      </element>
      <element name="TExtendedNotebook.BeginDragTab.Immediate">
        <short>
          True if the drag operation starts immediately and the drag threshold is ignored.
        </short>
      </element>
      <element name="TExtendedNotebook.BeginDragTab.Threshold">
        <short>
          Distance that the mouse must move before the drag operation starts, or -1 to use the default value from the drag manager.
        </short>
      </element>

      <element name="TExtendedNotebook.DraggingTabIndex">
        <short>Ordinal position for the tab affected by a drag operation.</short>
        <descr>
          <p>
            DraggingTabIndex is a read-only Integer property which contains the ordinal position for the tab or page active in a drag and drop operation. Its value is assigned in methods like BeginDragTab, DoEndDrag,  and DragCanceled. The value is set to -1 when drag and drop is not active for the control.
          </p>
          <p>
            Its value is used in the DragOver and DragDrop methods, and is passed as an argument to event handlers signalled in the class instance.
          </p>
        </descr>
        <seealso>
          <link id="TExtendedNotebook.BeginDragTab"/>
          <link id="TExtendedNotebook.DoEndDrag"/>
          <link id="TExtendedNotebook.DragCanceled"/>
          <link id="TExtendedNotebook.DragOver"/>
          <link id="TExtendedNotebook.DragDrop"/>
        </seealso>
      </element>

      <element name="TExtendedNotebook.OnTabDragOver">
        <short>
          Event handler signalled when the mouse hovers over a tab on the control during a drag operation.
        </short>
        <descr/>
        <seealso/>
      </element>

      <element name="TExtendedNotebook.OnTabDragOverEx">
        <short>
          Event handler signalled when the Ctrl key is held while dragging a tab on the control.
        </short>
        <descr/>
        <seealso/>
      </element>

      <element name="TExtendedNotebook.OnTabDragDrop">
        <short>
          Event handler signalled when an object is dropped onto a tab on the control.
        </short>
        <descr/>
        <seealso/>
      </element>

      <element name="TExtendedNotebook.OnTabDragDropEx">
        <short>
          Event handler signalled when an object is dropped onto a tab on the control while the Ctrl key is held.
        </short>
        <descr/>
        <seealso/>
      </element>

      <element name="TExtendedNotebook.OnTabEndDrag">
        <short>
          Event handler signalled when a drag operation is ended for a tab on the control.
        </short>
        <descr/>
        <seealso/>
      </element>

      <element name="TExtendedNotebook.OnTabStartDrag">
        <short>
          Event handler signalled when a drag operation is started for a tab on the control.
        </short>
        <descr/>
        <seealso/>
      </element>

      <element name="TExtendedNotebook.TabDragMode">
        <short>
          Indicates how a Drag operation is started for a tab on the control.
        </short>
        <descr>
          <p>
            The default value for the property is <var>dmManual</var>, and indicates that the operation is started in code executed by OnTabStartDrag event handler for the control. When set to <var>dmAutomatic</var>, the drag operation is initialized in the MouseDown method when the left mouse button is clicked on a tab for the notebook control.
          </p>
        </descr>
        <seealso/>
      </element>

      <element name="TExtendedNotebook.TabDragAcceptMode">
        <short>
          Default accept mode for a drag operation for a tab.
        </short>
        <descr>
          <p>
            <var>TabDragAcceptMode</var> is a <var>TDragMode</var> property which indicates how a dragged tab is accepted on the destination control. It is used in the DragDrop method to determine whether the tab is positioned automatically, or handled in code assigned to an event handler.
          </p>
          <p>
            The default value for the property is <var>dmManual</var>, and indicates that the tab is relocated manually in the OnTabDragDropEx event handler for the control. When set to <var>dmAutomatic</var>, the tab is automatically relocated using the Move method in the Pages collection for the control.
          </p>
        </descr>
        <seealso/>
      </element>

    </module>

  </package>
</fpdoc-descriptions>