GitLocker: The Coding Marketplace

Description:

ctkentrymsg 0.0.5

CTkEntryMsg

CTkEntry widget with messages
CTkEntry widget with provision to add
short information, warning, and error messages below the widget.

Features

Set default messages
Show information, warning, errors
Set timeout for errors and warnings
Chain multiple messages

Installation
pip3 install ctkentrymsg
Usage
entry = CTkEntryMsg(root,...)

Basic Example
from ctkentrymsg import CTkEntryMsg
from customtkinter import CTk, CTkLabel

root = CTk()

root.title('CTkEntryMsg Example')

CTkLabel(root, text='Username', width=100).grid(
row=0, column=0, sticky='nw', padx=(2,0), pady=(10,0))

username = CTkEntryMsg(
root,
default_msg='* letter,digits, special chars (min 8 chars)',
msg_default_color='blue',
highlight=True,
width=300)
username.grid(row=0, column=1, sticky='ne', pady=(5,0), padx=(0,5))
# showing an error
username.showerror(msg='Username cannot be blank')

root.mainloop()

Output:

Arguments

Argument
Description

master
root, tkinter.Frame or CTkFrame

default_msg
optional default message to show under Entry widget

msg_default_color
default message text color. Defaults to #000000

msg_warn_color
message text color for warnings. Defaults to #FC8309

msg_error_color
message text color for errors. Defaults to #FC0909

msg_font: tuple
message font. Defaults to ('Arial', 12)

msg_pos (str)
place message above or below the entry. Valid values - 'top', 'bottom'. Defaults to 'bottom'.

highlight
change entry widget's foreground color on warning or error. Default is True

highlight_warn_color
foreground color for entry on warning. Defaults to #FAC36A

highlight_error_color
foreground color for entry on error. Defaults to #FF9090

msg_timeout
global message timeout (in milliseconds) for warnings and errors. Defaults to 3000 ms

Methods

Method
Description

.restore_msg()
Restores message to default state

.restore_entry()
Restores entry widget to default state

.showerror(msg,...)
Displays error

.showwarn(msg,...)
Displays warning

.msg_queue(messages)
Chains multiple messages

Inherited methods from CTkEntry widget

Method
Description

.configure(*args, **kwargs)
Configure CTkEntry widget's attribute. Ex: entry.configure(fg_color="#000000")

.cget(attribute_name)
Returns value for attribute (passed as string) Ex: state = entry.cget("state")

.bind(*args, **kwargs)
Bind command function to event specified by sequence

.delete(first_index, last_index=None)
Deletes characters from the widget, starting with the one at index first_index, up to but not including the character at position last_index. If the second argument is omitted, only the single character at position first is deleted.

.insert(index, string)
Inserts string before the character at the given index

.get()
Returns current string in the entry.

.focus()
Set the focus on the CTkEntry widget

.focus_force()
Focuses a widget and the window it's in, immediately

.index(index)
Shift the contents of the entry so that the character at the given index is the leftmost visible character. Has no effect if the text fits entirely within the entry.

.icursor(index)
Set the insertion cursor just before the character at the given index.

.select_adjust(index)
This method is used to make sure that the selection includes the character at the specified index. If the selection already includes that character, nothing happens. If not, the selection is expanded from its current position (if any) to include position index.

.select_from(index)
Sets the tk.ANCHOR index position to the character selected by index, and selects that character.

.select_clear()
Clears the selection. If there isn't currently a selection, has no effect.

.select_present()
If there is a selection, returns true, else returns false.

.select_range(start_index, end_index)
Sets the selection under program control. Selects the text starting at the start index, up to but not including the character at the end index. The start position must be before the end position.

.select_to(index)
Selects all the text from the tk.ANCHOR position up to but not including the character at the given index.

.xview(index)
Same as .xview(). This method is useful in linking the Entry widget to a horizontal scrollbar.

.xview_moveto(f)
Positions the text in the entry so that the character at position f, relative to the entire text, is positioned at the left edge of the window. The f argument must be in the range [0,1], where 0 means the left end of the text and 1 the right end.

.xview_scroll(number, what)
Used to scroll the entry horizontally. The what argument must be either tk.UNITS, to scroll by character widths, or tk.PAGES, to scroll by chunks the size of the entry widget. The number is positive to scroll left to right, negative to scroll right to left. For example, for an entry widget e, e.xview_scroll(-1, tk.PAGES) would move the text one “page” to the right, and e.xview_scroll(4, tk.UNITS) would move the text four characters to the left.

More Examples
Chaining Messages
Queues the messages and shows them one after another, seperated at an interval specified in
timeout or msg_timeout argument.
entry = CTkEntryMsg(root, width=300)
messages = [
('error', 'An error message', 1000),
('warn', 'A warning message', 1000),
('error', 'Another error')
]
entry.msg_queue(messages)

Persistent messages
Keeps the message and the entry widget highlighted even after timeout.
entry = CTkEntryMsg(root, width=300)
entry.showwarn(
msg='This is a warning',
persist_msg: bool = True,
persist_highlight: bool = True)

Setting Message Timeout
Set a default timeout or message specific timeout
# timeout for all messages
entry = CTkEntryMsg(root, ..., msg_timeout=2000)
# this error is shown for 2 seconds
entry.showwarn('This is an error')
# this error is shown only for 1 second
entry.showerror('This is an error', timeout=1000)

Setting Attributes
entry = CTkEntryMsg(
root,
fg_color='black',
text_color='white',
width=300)

You can also use .configure(...)
entry.configure(font=('Arial', 12), width=400,...)

Change Log
[0.0.5] - 2024-01-03

Added msg_pos parameter - placement of messages on top or bottom of the entry widget

[0.0.4] - 2023-12-25

Removed unused param from docstring

[0.0.3] - 2023-12-25
Bug fix:

added padding for warnings

[0.0.2] - 2023-12-25
Bug fix:

fixed packaging error

[0.0.1] - 2023-12-25

First Release