DekGenius.com
[ Team LiB ] Previous Section Next Section

Controlmarshal by reference, disposable

System.Windows.Forms (system.windows.forms.dll)class

This is the fundamental base class for all the controls and forms in the framework.

After constructing a Control, you can add it to the Controls collection of a parent control and Show() it. (You can subsequently Hide() it again or change the Visible property.) You can also toggle whether it is Enabled.

Adding it to the Controls collection causes its Parent property to be set appropriately. HasChildren determines whether this control contains any children itself. Its index in the parent collection also determines its position in the z-order. You can use BringToFront() and SendToBack() for gross control of this feature.

TopLevelControl returns the top-level container—this is (usually) the outermost Form in which you will find the control. Note that if the control is contained in a TabPage that is not currently showing in the TabControl, the TopLevelControl property will return null.

You can set a ForeColor, BackColor, and Font with which to paint the control imagery (in particular, the Text). If you do not set these explicitly, it will inherit the AmbientProperties from its container. If all else fails, it will use the DefaultForeColor, DefaultBackColor, or DefaultFont. You can also specify a BackgroundImage that will be tiled across the control. Should the system theme or colors change, you can bind to the SystemColorsChanged event to update the controls appearance.

The general shape of the control can be specified with the Bounds property and SetBounds() method. To support nonrectangular controls you can assign a custom Region. Anything outside that region will be truly transparent.

You can query the ClientRectangle and the DisplayRectangle. In the base implementation, these are equivalent, but derived classes may return a smaller DisplayRectangle to account for some additional imagery when laying out children (a GroupBox-like control might do this, for example).

The Anchor and Dock properties are used by the default layout manager to determine how the control is moved and resized within it parent container. (See AnchorStyles and DockStyle for more details).

SuspendLayout() and ResumeLayout() temporarily disable (or reenable) layout management, and you can bind to the Layout event to provide your own layout handling. PerformLayout() forces the control to refresh the layout. You can also handle the Resize, Move, SizeChanged, and LocationChanged events if you are only interested in the controls bounding box, rather than full layout support. You can also Scale() the control and all its children by some factor. This is used by Form.AutoScale to manage the resizing of a form to allow for different sizes of default font.

Several members deal with the translation of coordinates from one system to another: RectangleToClient(), PointToClient(), RectangleToScreen(), and PointToScreen().

To support non-western scripts, you can also change the RightToLeft mode, and the ImeMode. Note that not all derived classes deal with these properties very well, but you should be aware of the need to support them when rendering your own custom controls.

Some controls can be selected or focused in their own right, whereas others (typically container controls) always pass their selection/focus on to another (such as a child). CanSelect and CanFocus determine whether this is the case. You can determine if the control or one of its children has the focus with the ContainsFocus property. If the control itself has the focus, the Focused property is true. You can set the Focus() to the control or Select() it. If you want to pass the activation on, call SelectNextControl() to give it up to the control with the next TabIndex. The TabIndex property controls the standard tab order, in conjunction with the TabStop flag. To track the selection/focus, bind to the Enter and Leave, or LostFocus and GotFocus events. The next item in the tab order is returned from the GetNextControl() method.

A right-click can be used to show a particular ContextMenu. Alternatively, you can handle the MouseDown, MouseUp, MouseWheel, MouseMove, MouseLeave, MouseEnter, and MouseHover events to deal with mouse activity. Note that you will only ever get one MouseHover event for each MouseEnter/MouseLeave pair. See MouseEventArgs for more information.

Similarly, keyboard support is provided via the KeyDown, KeyPress, and KeyUp events. See the KeyEventArgs and KeyPressEventArgs for more on this.

The user input can be validated by binding to the Validating and Validated events. If CausesValidation is true, any controls that require it will be validated when this control receives the focus. This slightly roundabout route to validation means your control must necessarily lose the focus to validate.

To support drag and drop, you can set the AllowDrop property to accept data dragged into the control. Handle the DragEnter, DragLeave, QueryContinueDrag, and DragDrop events to manage the drag-drop process. To initiate a drag from the control, simply call DoDragDrop(). The framework will pump messages for you until the drag is completed. See DataObject and DragEventArgs for more information on drag and drop.

It is important to know that Control objects have a strong thread affinity. While you can create controls on any thread, you cannot call any members from a thread other than that on which it was created. Even if you think you're getting away with it, don't do it! InvokeRequired determines whether you must use the Invoke() (or BeginInvoke()/EndInvoke()) methods first to marshal the call back onto the correct thread, or whether it can be called directly.

To handle custom painting for your control, you can override the protected OnPaint() and OnPaintBackground() members or bind to the Paint event. (Note that there is no PaintBackground event.) See PaintEventArgs for more information on this. At any time, you can use the CreateGraphics() method to create a graphics surface on which to paint (or measure) your imagery. You can Invalidate() portions of the control for repainting and force an immediate repaint with the Update() method, although updating can swiftly become inefficient, as the operating system already attempts to optimize the process.

public class Control : System.ComponentModel.Component : 
IOleControl, IOleObject, IOleInPlaceObject,
        IOleInPlaceActiveObject, IOleWindow, IViewObject, IViewObject2, IPersist, IPersistStreamInit, IPersistPropertyBag,
        IPersistStorage, IQuickActivate, System.ComponentModel.ISynchronizeInvoke, IWin32Window {
// Public Constructors
   public Control();
   public Control(Control parent, string text);
   public Control(Control parent, string text, int left, int top, int width, int height);
   public Control(string text);
   public Control(string text, int left, int top, int width, int height);
// Public Static Properties
   public static Color DefaultBackColor{get; }
   public static Font DefaultFont{get; }
   public static Color DefaultForeColor{get; }
   public static Keys ModifierKeys{get; }
   public static MouseButtons MouseButtons{get; }
   public static Point MousePosition{get; }
// Public Instance Properties
   public AccessibleObject AccessibilityObject{get; }
   public string AccessibleDefaultActionDescription{set; get; }
   public string AccessibleDescription{set; get; }
   public string AccessibleName{set; get; }
   public AccessibleRole AccessibleRole{set; get; }
   public virtual bool AllowDrop{set; get; }
   public virtual AnchorStyles Anchor{set; get; }
   public virtual Color BackColor{set; get; }
   public virtual Image BackgroundImage{set; get; }
   public virtual BindingContext BindingContext{set; get; }
   public int Bottom{get; }
   public Rectangle Bounds{set; get; }
   public bool CanFocus{get; }
   public bool CanSelect{get; }
   public bool Capture{set; get; }
   public bool CausesValidation{set; get; }
   public Rectangle ClientRectangle{get; }
   public Size ClientSize{set; get; }
   public string CompanyName{get; }
   public bool ContainsFocus{get; }
   public virtual ContextMenu ContextMenu{set; get; }
   public ControlCollection Controls{get; }
   public bool Created{get; }
   public virtual Cursor Cursor{set; get; }
   public ControlBindingsCollection DataBindings{get; }
   public virtual Rectangle DisplayRectangle{get; }
   public bool Disposing{get; }
   public virtual DockStyle Dock{set; get; }
   public bool Enabled{set; get; }
   public virtual bool Focused{get; }
   public virtual Font Font{set; get; }
   public virtual Color ForeColor{set; get; }
   public IntPtr Handle{get; }
// implements IWin32Window
   public bool HasChildren{get; }
   public int Height{set; get; }
   public ImeMode ImeMode{set; get; }
   public bool InvokeRequired{get; }
// implements System.ComponentModel.ISynchronizeInvoke
   public bool IsAccessible{set; get; }
   public bool IsDisposed{get; }
   public bool IsHandleCreated{get; }
   public int Left{set; get; }
   public Point Location{set; get; }
   public string Name{set; get; }
   public Control Parent{set; get; }
   public string ProductName{get; }
   public string ProductVersion{get; }
   public bool RecreatingHandle{get; }
   public Region Region{set; get; }
   public int Right{get; }
   public virtual RightToLeft RightToLeft{set; get; }
   public override ISite Site{set; get; } // overrides System.ComponentModel.Component
   public Size Size{set; get; }
   public int TabIndex{set; get; }
   public bool TabStop{set; get; }
   public object Tag{set; get; }
   public virtual string Text{set; get; }
   public int Top{set; get; }
   public Control TopLevelControl{get; }
   public bool Visible{set; get; }
   public int Width{set; get; }
   public IWindowTarget WindowTarget{set; get; }
// Protected Instance Properties
   protected virtual CreateParams CreateParams{get; }
   protected virtual ImeMode DefaultImeMode{get; }
   protected virtual Size DefaultSize{get; }
   protected int FontHeight{set; get; }
   protected bool RenderRightToLeft{get; }
   protected bool ResizeRedraw{set; get; }
   protected virtual bool ShowFocusCues{get; }
   protected bool ShowKeyboardCues{get; }
// Public Static Methods
   public static Control FromChildHandle(IntPtr handle);
   public static Control FromHandle(IntPtr handle);
   public static bool IsMnemonic(char charCode, string text);
// Protected Static Methods
   protected static bool ReflectMessage(IntPtr hWnd, ref Message m);
// Public Instance Methods
   public IAsyncResult BeginInvoke(Delegate method);
   public IAsyncResult BeginInvoke(Delegate method,
        object[ ] args);  // implements System.ComponentModel.ISynchronizeInvoke
   public void BringToFront();
   public bool Contains(Control ctl);
   public void CreateControl();
   public Graphics CreateGraphics();
   public DragDropEffects DoDragDrop(object data, DragDropEffects allowedEffects);
   public object EndInvoke(IAsyncResult asyncResult);  // implements System.ComponentModel.ISynchronizeInvoke
   public Form FindForm();
   public bool Focus();
   public Control GetChildAtPoint(System.Drawing.Point pt);
   public IContainerControl GetContainerControl();
   public Control GetNextControl(Control ctl, bool forward);
   public void Hide();
   public void Invalidate();
   public void Invalidate(bool invalidateChildren);
   public void Invalidate(System.Drawing.Rectangle rc);
   public void Invalidate(System.Drawing.Rectangle rc, bool invalidateChildren);
   public void Invalidate(System.Drawing.Region region);
   public void Invalidate(System.Drawing.Region region, bool invalidateChildren);
   public object Invoke(Delegate method);
   public object Invoke(Delegate method, object[ ] args);  // implements System.ComponentModel.ISynchronizeInvoke
   public void PerformLayout();
   public void PerformLayout(Control affectedControl, string affectedProperty);
   public Point PointToClient(System.Drawing.Point p);
   public Point PointToScreen(System.Drawing.Point p);
   public virtual bool PreProcessMessage(ref Message msg);
   public Rectangle RectangleToClient(System.Drawing.Rectangle r);
   public Rectangle RectangleToScreen(System.Drawing.Rectangle r);
   public virtual void Refresh();
   public virtual void ResetBackColor();
   public void ResetBindings();
   public virtual void ResetCursor();
   public virtual void ResetFont();
   public virtual void ResetForeColor();
   public void ResetImeMode();
   public virtual void ResetRightToLeft();
   public virtual void ResetText();
   public void ResumeLayout();
   public void ResumeLayout(bool performLayout);
   public void Scale(float ratio);
   public void Scale(float dx, float dy);
   public void Select();
   public bool SelectNextControl(Control ctl, bool forward, bool tabStopOnly, bool nested, bool wrap);
   public void SendToBack();
   public void SetBounds(int x, int y, int width, int height);
   public void SetBounds(int x, int y, int width, int height, BoundsSpecified specified);
   public void Show();
   public void SuspendLayout();
   public void Update();
// Protected Instance Methods
   protected void AccessibilityNotifyClients(AccessibleEvents accEvent, int childID);
   protected virtual AccessibleObject CreateAccessibilityInstance();
   protected virtual ControlCollection CreateControlsInstance();
   protected virtual void CreateHandle();
   protected virtual void DefWndProc(ref Message m);
   protected virtual void DestroyHandle();
   protected override void Dispose(bool disposing);  // overrides System.ComponentModel.Component
   protected bool GetStyle(ControlStyles flag);
   protected bool GetTopLevel();
   protected virtual void InitLayout();
   protected void InvokeGotFocus(Control toInvoke, EventArgs e);
   protected void InvokeLostFocus(Control toInvoke, EventArgs e);
   protected void InvokeOnClick(Control toInvoke, EventArgs e);
   protected void InvokePaint(Control c, PaintEventArgs e);
   protected void InvokePaintBackground(Control c, PaintEventArgs e);
   protected virtual bool IsInputChar(char charCode);
   protected virtual bool IsInputKey(Keys keyData);
   protected virtual void NotifyInvalidate(System.Drawing.Rectangle invalidatedArea);
   protected virtual void OnBackColorChanged(EventArgs e);
   protected virtual void OnBackgroundImageChanged(EventArgs e);
   protected virtual void OnBindingContextChanged(EventArgs e);
   protected virtual void OnCausesValidationChanged(EventArgs e);
   protected virtual void OnChangeUICues(UICuesEventArgs e);
   protected virtual void OnClick(EventArgs e);
   protected virtual void OnContextMenuChanged(EventArgs e);
   protected virtual void OnControlAdded(ControlEventArgs e);
   protected virtual void OnControlRemoved(ControlEventArgs e);
   protected virtual void OnCreateControl();
   protected virtual void OnCursorChanged(EventArgs e);
   protected virtual void OnDockChanged(EventArgs e);
   protected virtual void OnDoubleClick(EventArgs e);
   protected virtual void OnDragDrop(DragEventArgs drgevent);
   protected virtual void OnDragEnter(DragEventArgs drgevent);
   protected virtual void OnDragLeave(EventArgs e);
   protected virtual void OnDragOver(DragEventArgs drgevent);
   protected virtual void OnEnabledChanged(EventArgs e);
   protected virtual void OnEnter(EventArgs e);
   protected virtual void OnFontChanged(EventArgs e);
   protected virtual void OnForeColorChanged(EventArgs e);
   protected virtual void OnGiveFeedback(GiveFeedbackEventArgs gfbevent);
   protected virtual void OnGotFocus(EventArgs e);
   protected virtual void OnHandleCreated(EventArgs e);
   protected virtual void OnHandleDestroyed(EventArgs e);
   protected virtual void OnHelpRequested(HelpEventArgs hevent);
   protected virtual void OnImeModeChanged(EventArgs e);
   protected virtual void OnInvalidated(InvalidateEventArgs e);
   protected virtual void OnKeyDown(KeyEventArgs e);
   protected virtual void OnKeyPress(KeyPressEventArgs e);
   protected virtual void OnKeyUp(KeyEventArgs e);
   protected virtual void OnLayout(LayoutEventArgs levent);
   protected virtual void OnLeave(EventArgs e);
   protected virtual void OnLocationChanged(EventArgs e);
   protected virtual void OnLostFocus(EventArgs e);
   protected virtual void OnMouseDown(MouseEventArgs e);
   protected virtual void OnMouseEnter(EventArgs e);
   protected virtual void OnMouseHover(EventArgs e);
   protected virtual void OnMouseLeave(EventArgs e);
   protected virtual void OnMouseMove(MouseEventArgs e);
   protected virtual void OnMouseUp(MouseEventArgs e);
   protected virtual void OnMouseWheel(MouseEventArgs e);
   protected virtual void OnMove(EventArgs e);
   protected virtual void OnNotifyMessage(Message m);
   protected virtual void OnPaint(PaintEventArgs e);
   protected virtual void OnPaintBackground(PaintEventArgs pevent);
   protected virtual void OnParentBackColorChanged(EventArgs e);
   protected virtual void OnParentBackgroundImageChanged(EventArgs e);
   protected virtual void OnParentBindingContextChanged(EventArgs e);
   protected virtual void OnParentChanged(EventArgs e);
   protected virtual void OnParentEnabledChanged(EventArgs e);
   protected virtual void OnParentFontChanged(EventArgs e);
   protected virtual void OnParentForeColorChanged(EventArgs e);
   protected virtual void OnParentRightToLeftChanged(EventArgs e);
   protected virtual void OnParentVisibleChanged(EventArgs e);
   protected virtual void OnQueryContinueDrag(QueryContinueDragEventArgs qcdevent);
   protected virtual void OnResize(EventArgs e);
   protected virtual void OnRightToLeftChanged(EventArgs e);
   protected virtual void OnSizeChanged(EventArgs e);
   protected virtual void OnStyleChanged(EventArgs e);
   protected virtual void OnSystemColorsChanged(EventArgs e);
   protected virtual void OnTabIndexChanged(EventArgs e);
   protected virtual void OnTabStopChanged(EventArgs e);
   protected virtual void OnTextChanged(EventArgs e);
   protected virtual void OnValidated(EventArgs e);
   protected virtual void OnValidating(System.ComponentModel.CancelEventArgs e);
   protected virtual void OnVisibleChanged(EventArgs e);
   protected virtual bool ProcessCmdKey(ref Message msg, Keys keyData);
   protected virtual bool ProcessDialogChar(char charCode);
   protected virtual bool ProcessDialogKey(Keys keyData);
   protected virtual bool ProcessKeyEventArgs(ref Message m);
   protected internal virtual bool ProcessKeyMessage(ref Message m);
   protected virtual bool ProcessKeyPreview(ref Message m);
   protected virtual bool ProcessMnemonic(char charCode);
   protected void RaiseDragEvent(object key, DragEventArgs e);
   protected void RaiseKeyEvent(object key, KeyEventArgs e);
   protected void RaiseMouseEvent(object key, MouseEventArgs e);
   protected void RaisePaintEvent(object key, PaintEventArgs e);
   protected void RecreateHandle();
   protected void ResetMouseEventArgs();
   protected ContentAlignment RtlTranslateAlignment(System.Drawing.ContentAlignment align);
   protected HorizontalAlignment RtlTranslateAlignment(HorizontalAlignment align);
   protected LeftRightAlignment RtlTranslateAlignment(LeftRightAlignment align);
   protected ContentAlignment RtlTranslateContent(System.Drawing.ContentAlignment align);
   protected HorizontalAlignment RtlTranslateHorizontal(HorizontalAlignment align);
   protected LeftRightAlignment RtlTranslateLeftRight(LeftRightAlignment align);
   protected virtual void ScaleCore(float dx, float dy);
   protected virtual void Select(bool directed, bool forward);
   protected virtual void SetBoundsCore(int x, int y, int width, int height, BoundsSpecified specified);
   protected virtual void SetClientSizeCore(int x, int y);
   protected void SetStyle(ControlStyles flag, bool value);
   protected void SetTopLevel(bool value);
   protected virtual void SetVisibleCore(bool value);
   protected void UpdateBounds();
   protected void UpdateBounds(int x, int y, int width, int height);
   protected void UpdateBounds(int x, int y, int width, int height, int clientWidth, int clientHeight);
   protected void UpdateStyles();
   protected void UpdateZOrder();
   protected virtual void WndProc(ref Message m);
// Events
   public event EventHandler BackColorChanged;
   public event EventHandler BackgroundImageChanged;
   public event EventHandler BindingContextChanged;
   public event EventHandler CausesValidationChanged;
   public event UICuesEventHandler ChangeUICues;
   public event EventHandler Click;
   public event EventHandler ContextMenuChanged;
   public event ControlEventHandler ControlAdded;
   public event ControlEventHandler ControlRemoved;
   public event EventHandler CursorChanged;
   public event EventHandler DockChanged;
   public event EventHandler DoubleClick;
   public event DragEventHandler DragDrop;
   public event DragEventHandler DragEnter;
   public event EventHandler DragLeave;
   public event DragEventHandler DragOver;
   public event EventHandler EnabledChanged;
   public event EventHandler Enter;
   public event EventHandler FontChanged;
   public event EventHandler ForeColorChanged;
   public event GiveFeedbackEventHandler GiveFeedback;
   public event EventHandler GotFocus;
   public event EventHandler HandleCreated;
   public event EventHandler HandleDestroyed;
   public event HelpEventHandler HelpRequested;
   public event EventHandler ImeModeChanged;
   public event InvalidateEventHandler Invalidated;
   public event KeyEventHandler KeyDown;
   public event KeyPressEventHandler KeyPress;
   public event KeyEventHandler KeyUp;
   public event LayoutEventHandler Layout;
   public event EventHandler Leave;
   public event EventHandler LocationChanged;
   public event EventHandler LostFocus;
   public event MouseEventHandler MouseDown;
   public event EventHandler MouseEnter;
   public event EventHandler MouseHover;
   public event EventHandler MouseLeave;
   public event MouseEventHandler MouseMove;
   public event MouseEventHandler MouseUp;
   public event MouseEventHandler MouseWheel;
   public event EventHandler Move;
   public event PaintEventHandler Paint;
   public event EventHandler ParentChanged;
   public event QueryAccessibilityHelpEventHandler QueryAccessibilityHelp;
   public event QueryContinueDragEventHandler QueryContinueDrag;
   public event EventHandler Resize;
   public event EventHandler RightToLeftChanged;
   public event EventHandler SizeChanged;
   public event EventHandler StyleChanged;
   public event EventHandler SystemColorsChanged;
   public event EventHandler TabIndexChanged;
   public event EventHandler TabStopChanged;
   public event EventHandler TextChanged;
   public event EventHandler Validated;
   public event CancelEventHandler Validating;
   public event EventHandler VisibleChanged;
}

Hierarchy

System.Object System.MarshalByRefObject System.ComponentModel.Component(System.ComponentModel.IComponen, System.IDisposable) Control(IOleContro, IOleObject, IOleInPlaceObject, IOleInPlaceActiveObject, IOleWindow, IViewObject, IViewObject2, IPersist, IPersistStreamInit, IPersistPropertyBag, IPersistStorage, IQuickActivate, System.ComponentModel.ISynchronizeInvoke, IWin32Window)

Subclasses

Multiple types

Returned By

Multiple types

Passed To

Multiple types

    [ Team LiB ] Previous Section Next Section