Table of Contents

Numpad and pattern entry

TTMSFNCPassLock supports two entry modes. Numpad (pltNumber) presents a 3×4 grid of digit buttons. Pattern (pltPattern) presents a 3×3 grid of dots that the user connects by dragging. Both modes auto-centre their buttons and entry indicators within the component bounds.

Choosing the lock type

TMSFNCPassLock1.Options.LockType := pltNumber;  // numeric keypad
// or
TMSFNCPassLock1.Options.LockType := pltPattern;  // connect-the-dots

Fixed-length vs. variable-length passwords

By default the component expects a fixed-length password. Set PasswordValue to the stored password and leave Options.ShowPasswordLength as True. The component automatically checks the entry once the length of PasswordEntry equals the length of PasswordValue.

For a variable-length password, show the OK button instead:

TMSFNCPassLock1.Options.ShowOKButton := True;
// User presses OK when done; length is not constrained

To also allow the user to clear the last digit or dot, show the CE button:

TMSFNCPassLock1.Options.ShowClearEntryButton := True;

Reading the entered value

PasswordEntry holds what the user has typed so far. OnPasswordCheck fires when the component is ready to compare entry to password. Use the AMatch parameter to override the comparison if you store passwords hashed:

procedure TForm1.TMSFNCPassLock1PasswordCheck(Sender: TObject;
  AEntry: string; var AMatch: Boolean);
begin
  // Custom comparison — e.g. compare against a stored hash
  AMatch := VerifyHash(AEntry, StoredPasswordHash);
end;

Learn mode — letting users set a new password

Enable Options.LearnMode to start the flow. The user enters a new password (OnLearnPassword), then confirms it by entering it again (OnConfirmPassword). When both match, OnNewPassword fires and PasswordValue is updated:

// Start learn flow so the user can set a new PIN
procedure TForm1.StartLearnMode;
begin
  TMSFNCPassLock1.Options.LearnMode := True;
end;

// Called when the user finishes entering the first instance of the new password
procedure TForm1.TMSFNCPassLock1LearnPassword(Sender: TObject; APassword: string);
begin
  StatusLabel.Text := 'Enter the same PIN again to confirm.';
end;

// Called when the user enters the same password a second time
procedure TForm1.TMSFNCPassLock1ConfirmPassword(Sender: TObject; APassword: string);
begin
  StatusLabel.Text := 'Confirming...';
end;

// Called when both entries match — the new password is now active
procedure TForm1.TMSFNCPassLock1NewPassword(Sender: TObject; APassword: string);
begin
  StoredPasswordHash := HashPassword(APassword);  // persist the new password
  TMSFNCPassLock1.Options.LearnMode := False;      // exit learn mode
  StatusLabel.Text := 'New PIN saved.';
end;

Always disable learn mode again after OnNewPassword if you only want a one-time setup flow.

Keyboard input

TMSFNCPassLock1.Options.EnableKeyboardInput := True;

Digits typed on the keyboard are treated as button presses in numpad mode. Keyboard input has no effect in pattern mode.

Appearance customisation

ButtonAppearance controls the normal, hover, and down states of each button, plus shape and maximum size:

TMSFNCPassLock1.ButtonAppearance.Shape := plbsRoundedRectangle;
TMSFNCPassLock1.ButtonAppearance.MaxSize := 60;  // maximum button size in pixels; -1 = fill all available space
TMSFNCPassLock1.ButtonAppearance.Fill.Color := $001A73E8;
TMSFNCPassLock1.ButtonAppearance.Font.Color := claWhite;
TMSFNCPassLock1.ButtonAppearance.CaptionOK := 'Unlock';
TMSFNCPassLock1.ButtonAppearance.CaptionClearEntry := '⌫';

EntryAppearance controls the entry-indicator dots:

TMSFNCPassLock1.EntryAppearance.Fill.Color := $001A73E8;
TMSFNCPassLock1.EntryAppearance.DownFill.Color := $0015A34A;
TMSFNCPassLock1.EntryAppearance.MaxSize := 18;

Custom draw hooks

All drawing is customisable through Before/After draw events. Each event receives the current TTMSFNCGraphics context and the bounding rectangle. Set ADefaultDraw := False in a Before event to suppress the default rendering:

procedure TForm1.TMSFNCPassLock1BeforeDrawButton(Sender: TObject;
  AGraphics: TTMSFNCGraphics; ARect: TRectF;
  AButtonShape: TTMSFNCPassLockButtonShape; AValue: string;
  var AAllow, ADefaultDraw: Boolean);
begin
  // Highlight the '5' button in a different colour
  if AValue = '5' then
  begin
    AGraphics.Fill.Color := $00FF9800;
    AGraphics.DrawEllipse(ARect);
    ADefaultDraw := False;
  end;
end;

Combining learn mode and hashed passwords

The example below stores a bcrypt-style hash in PasswordValue and uses OnPasswordCheck and OnNewPassword together with learn mode:

// Initialise: use hashed password comparison + pattern mode
procedure TForm1.FormCreate(Sender: TObject);
begin
  with TMSFNCPassLock1 do
  begin
    Options.LockType := pltPattern;
    Options.ShowEntry := True;
    Options.EnableKeyboardInput := False;
    // Set an empty value; actual check is done via OnPasswordCheck
    PasswordValue := '!hashed'; // placeholder
    ButtonAppearance.Shape := plbsCircle;
    ButtonAppearance.MaxSize := 56;
    EntryAppearance.MaxSize := 16;
  end;
end;

// Replace the built-in string comparison with a hash comparison
procedure TForm1.TMSFNCPassLock1PasswordCheck(Sender: TObject;
  AEntry: string; var AMatch: Boolean);
begin
  AMatch := VerifyHash(AEntry, GetStoredHash);
  if AMatch then
    ShowMessage('Access granted')
  else
    ShowMessage('Incorrect pattern — try again');
end;

// Persist a newly learned password as a hash
procedure TForm1.TMSFNCPassLock1NewPassword(Sender: TObject; APassword: string);
begin
  SaveHash(HashPassword(APassword));
  TMSFNCPassLock1.Options.LearnMode := False;
end;