Mtf.Controls 1.0.4

Mtf.Controls Documentation

Overview

This documentation provides guidance on using the Mtf.Controls library in your project, which includes customizable controls like ListView, TreeView, and Panel elements.

To install the Mtf.Controls package, follow these steps:

1. Add Package:

   • Open the terminal in your project directory.

   • Run the following command:

     dotnet add package Mtf.Controls
     

   This will automatically download and reference the Mtf.Controls library in your project.

2. Include the Namespace: At the top of your code file, include the Mtf.Controls namespace:

   using Mtf.Controls;
   

Using Custom Controls

PasswordBox Control

The PasswordBox control in Mtf.Controls extends the standard TextBox to provide a secure way to handle password input. Unlike a regular TextBox with PasswordChar, the PasswordBox stores the password as a SecureString and handles input securely, preventing sensitive data from being stored in plain text.

Attributes

• [ToolboxItem(true)] � Ensures that the control is available in the Toolbox.
• [ToolboxBitmap(typeof(PasswordBox), "Resources.PasswordBox.png")] � Associates an icon for the control in the Toolbox.

Constructor

• PasswordBox(): Initializes a new PasswordBox with a default PasswordChar (*).

Properties

Methods

• OnKeyPress(KeyPressEventArgs e): Handles key press events to update the SecureString (password) instead of storing characters in plain text. Prevents the actual character from being displayed.
• OnTextChanged(EventArgs e): Clears the SecureString when the Text property is cleared.
• OnKeyDown(KeyEventArgs e): Manages additional key events such as backspace or delete to ensure password remains consistent with displayed text.
• Dispose(): Overrides Dispose() to securely clear and release the SecureString when the control is disposed of.

SecureString Handling

The PasswordBox uses a SecureString to store the password securely. This ensures that sensitive data isn't held in memory in plain text, reducing the risk of exposure.

Example Usage

using System;
using System.Security;
using System.Windows.Forms;
using Mtf.Controls;

public class LoginForm : Form
{
    private PasswordBox passwordBox;

    public LoginForm()
    {
        passwordBox = new PasswordBox
        {
            Location = new System.Drawing.Point(10, 10),
            Width = 200
        };
        Controls.Add(passwordBox);
    }

    public SecureString GetPassword()
    {
        return passwordBox.Password;  // Use this to retrieve the secure password input
    }
}

In this example, LoginForm creates a PasswordBox control to securely capture a password. The password can be retrieved as a SecureString by calling GetPassword().

ListView Control

MtfListView Class Documentation

The MtfListView class is a custom ListView control that enhances the standard functionality with additional features such as alternating colors, compact view, and integrated thread safe behaviour. It is designed to improve the visual appearance and usability of list views in applications.

Attributes

• ToolboxItem: Indicates that the control is a toolbox item.
• ToolboxBitmap: Provides a bitmap for the control in the toolbox.

Constructor

MtfListView()

Initializes a new instance of the MtfListView class, setting default values for its properties.

Properties

Example Usage

[ToolboxItem(true)]
[ToolboxBitmap(typeof(MtfListView), "Resources.MtfListView.png")]
public class MtfListView : ListView
{
    private readonly List<int> alwaysDifferentColumnIndexes = new List<int>();

    public MtfListView()
    {
        EnsureLastItemIsVisible = false;
        AlternatingColorsAreInUse = true;
        FirstItemIsGray = false;
        OwnerDraw = AlternatingColorsAreInUse;
        SetStyle(ControlStyles.OptimizedDoubleBuffer | ControlStyles.AllPaintingInWmPaint | ControlStyles.EnableNotifyMessage | ControlStyles.UserPaint, true);
        UpdateStyles();

        View = View.Details;
        FullRowSelect = true;
        AlternatingColorEven = Color.LightBlue;
        AlternatingColorOdd = BackColor;

        AlternatingPairColorEven = Color.LightSeaGreen;
        AlternatingPairColorOdd = Color.CadetBlue;
        SameItemsColorEven = Color.DarkOrange;
        SameItemsColorOdd = Color.LightSalmon;
        CompactView = false;
    }

    // Properties
    [Browsable(true)]
    [DesignerSerializationVisibility(DesignerSerializationVisibility.Visible)]
    [Description("Indicates that the item checkboxes are readonly or not.")]
    public bool ReadonlyCheckboxes { get; set; }

    [Browsable(true)]
    [DesignerSerializationVisibility(DesignerSerializationVisibility.Visible)]
    [Description("Ensures that the last item is visible.")]
    public bool EnsureLastItemIsVisible { get; set; }

    // Additional properties...
}

FileBrowserView class

Properties

MtfTreeView Class

The MtfTreeView class extends TreeView with features like custom line styles, multiple selection support, custom checkbox appearance, and tick color.

Constants

Properties

Usage Example

var treeView = new MtfTreeView
{
    MultiSelect = true,
    TickColor = Color.Green,
    LineStyle = DashStyle.Dot
};

SourceCodeViewerRichTextBox

SourceCodeViewerRichTextBox is a custom control derived from the RichTextBox class. It provides functionality for displaying source code with customizable syntax coloring and improved control over text rendering and updates.

Features

• Syntax Highlighting: Supports multiple coloring methods, such as C++/CLI, C#, Java, Object Pascal, Visual Basic, and Visual C++.
• Thread-Safe Text Manipulation: Safe methods for appending and setting text in multithreaded applications.
• Efficient Updates: Supports batch updates without flickering, with options to begin and end updates manually.
• Customizable Tab Size: Dynamically calculates tab width based on font size.
• Optional Auto-Scrolling: Ensures the last line of text is visible on updates if configured.

Constructors

SourceCodeViewerRichTextBox()

Initializes the control, setting default options for:

• Disabling URL detection
• Accepting tabs
• No initial coloring

Properties

ColoringMethod (ColoringMethod)

Defines the syntax coloring mode.

• Type: ColoringMethod
• Default: ColoringMethod.No_Coloring
• Usage: Set to any of the supported programming languages to enable syntax highlighting for that language.

ScroolToLastLine (bool)

Determines whether the control automatically scrolls to the last line on each update.

• Type: bool
• Default: false
• Description: Set to true to enable auto-scrolling to the last line.

Methods

GetTextThreadSafe()

Returns the control�s text safely in a multithreaded environment.

SetTextThreadSafe(string text)

Sets the control�s text safely in a multithreaded environment.

AppendTextThreadSafe(string text, Color? textColor = null)

Appends text to the control safely in a multithreaded environment, with an optional text color.

BeginUpdate()

Disables control updates to prevent flickering during batch operations.

EndUpdate()

Re-enables control updates after a batch operation and redraws the control.

StartUpdate(ref int scrollTo, ref int pos, ref int len)

Starts a safe update process by caching the current scroll and cursor positions.

StopUpdate(int scrollTo, int pos, int len)

Ends the update process, restoring the control's scroll and cursor positions.

ClearColoring()

Resets all text colors to the default font color.

ClearBackgroundColoring()

Resets the background color of all text to the control�s background color.

ApplyColoring()

Applies syntax coloring based on the configured ColoringMethod.

Supported Coloring Methods

1. No_Coloring - Disables all syntax highlighting.
2. CPP_CLI - Syntax highlighting for C++/CLI.
3. C_Sharp - Syntax highlighting for C#.
4. Java - Syntax highlighting for Java.
5. Object_Pascal - Syntax highlighting for Object Pascal.
6. Visual_Basic - Syntax highlighting for Visual Basic.
7. Visual_CPP - Syntax highlighting for Visual C++.

Example Usage

var codeViewer = new SourceCodeViewerRichTextBox
{
    ColoringMethod = ColoringMethod.C_Sharp,
    ScroolToLastLine = true
};
codeViewer.SetTextThreadSafe("public class HelloWorld { }");

MovablePanel

MovablePanel is a transparent panel that can be moved by dragging it with the mouse. It is useful in scenarios where dynamic relocation of a window or panel is needed. The following attributes and events are available:

Attributes

• [ToolboxItem(true)] � Ensures the control is available in the Toolbox.
• [ToolboxBitmap(typeof(MovablePanel), "Resources.MovablePanel.bmp")] � Associates a custom icon for the panel in the Toolbox.

Properties

• CanMove (bool): Determines if the panel is movable. Default is true.

Methods

• OnMouseDown(MouseEventArgs e): Initiates the panel's movement when the mouse button is pressed, if CanMove is set to true.
• OnMouseUp(MouseEventArgs e): Stops moving the panel when the mouse button is released.
• OnMouseMove(MouseEventArgs e): Updates the panel's position as the mouse is moved, as long as movement is allowed.

Usage Example

var panel = new MovablePanel
{
    CanMove = true
};

MovableSizablePanel

MovableSizablePanel extends MovablePanel, adding the capability to resize the panel in the East (right), South (bottom), and South-East (bottom-right) directions.

Attributes

• [Browsable(true)], [DesignerSerializationVisibility(DesignerSerializationVisibility.Visible)], [Description("Can change the size of the panel")] � Allows the CanSize property to be visible and modifiable in the designer.

Properties

• CanSize (bool): Determines if the panel is resizable. Default is true.

Methods

• InitializeResizeHandles(): Creates resize handles on the panel's right, bottom, and bottom-right sides.
• CheckSize(): Ensures the panel does not shrink below a predefined minimum size (Constants.MinSize).
• PbEast_MouseMove, PbSouth_MouseMove, PbSouthEast_MouseMove: Logic for resizing in specific directions.

Usage Example

var sizablePanel = new MovableSizablePanel
{
    CanMove = true,
    CanSize = true
};

MtfPictureBox

MtfPictureBox is a custom PictureBox control that supports resizable and repositionable inner controls during resizing. It is particularly useful for displaying elements with relative positions that need to adapt dynamically to changes in size.

Attributes

• [ToolboxItem(true)] � Ensures the control is available in the Toolbox.
• [ToolboxBitmap(typeof(MtfPictureBox), "Resources.MtfPictureBox.png")] � Associates a custom icon for the PictureBox in the Toolbox.

Properties

• RepositioningAndResizingControlsOnResize (bool): Specifies whether controls added to the PictureBox should resize and reposition automatically.
• OriginalSize (Size): Stores the original size for scaling calculations.

Methods

• OnControlAdded(ControlEventArgs e): Stores the position and size of a new control added to the PictureBox.
• OnControlRemoved(ControlEventArgs e): Deletes position and size information of a control when it�s removed.
• RefreshLocation(Control control): Updates the position of a given control.
• RefreshSize(Control control): Updates the size of a given control.
• RelocateControls(): Relocates all controls based on the new scaling ratio.

Usage Example

var pictureBox = new MtfPictureBox
{
    RepositioningAndResizingControlsOnResize = true,
    OriginalSize = new Size(800, 600)
};

Constants

This project uses a Constants class to store shared values such as:

• MinSize (Size): Minimum size allowed for resizable panels, ensuring they do not shrink below this threshold.
• Border (int): Defines the size of the resize borders on the MovableSizablePanel.

Ensure the Constants class is defined appropriately for the panels to function as expected.

Notes

• MovablePanel and MovableSizablePanel rely on the Constants class for settings like MinSize and Border.
• MtfPictureBox should be initialized with the OriginalSize property set to the initial dimensions, so it can calculate scaling accurately.
• The methods handling resizing (PbEast_MouseMove, PbSouth_MouseMove, and PbSouthEast_MouseMove) require careful handling of mouse events to avoid conflicts with other mouse-based controls on the form.

Important Notes

• Ensure your project has .NET dependencies to support Mtf.Controls.
• For more details on using specific methods or properties, refer to the Mtf.Controls GitHub Repository.
• If you have problems with the Visual Studio Toolbox, remove all files from C:\Users\morte\AppData\Local\Microsoft\VisualStudio[vs_version_]\ComponentModelCache. After a rebuild, the toolbox should include these controls.

Feel free to reach out if further clarification is needed!