# CTkEntryMsg
### CTkEntry widget with messages
CTkEntry widget with provision to add
short information, warning, and error messages below the widget.
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/shine-jayakumar/CTkEntryMsg/master/doc_images/ctkentrymsg_demo.gif">
<img src="https://raw.githubusercontent.com/shine-jayakumar/CTkEntryMsg/master/doc_images/ctkentrymsg_demo.gif">
</picture>
</p>
## 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:**
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/shine-jayakumar/CTkEntryMsg/master/doc_images/basic_usage.png">
<img src="https://raw.githubusercontent.com/shine-jayakumar/CTkEntryMsg/master/doc_images/basic_usage.png">
</picture>
</p>
## 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 |
<br/>
**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
Raw data
{
"_id": null,
"home_page": "https://github.com/shine-jayakumar/CTkEntryMsg",
"name": "ctkentrymsg",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "ctkentrymsg,customtkinter,tkinter,ctkentry, ctkentry-show-message",
"author": "Shine Jayakumar",
"author_email": "shinejayakumar@yahoo.com",
"download_url": "https://files.pythonhosted.org/packages/a2/a8/d0157baeb12a90b8dd70e35f4ecf9166ba903063f3d61287804022e87c7c/ctkentrymsg-0.0.5.tar.gz",
"platform": null,
"description": "# CTkEntryMsg\n\n\n\n\n### CTkEntry widget with messages\n\nCTkEntry widget with provision to add \nshort information, warning, and error messages below the widget.\n\n<p align=\"center\">\n <picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/shine-jayakumar/CTkEntryMsg/master/doc_images/ctkentrymsg_demo.gif\">\n <img src=\"https://raw.githubusercontent.com/shine-jayakumar/CTkEntryMsg/master/doc_images/ctkentrymsg_demo.gif\">\n </picture>\n</p>\n\n## Features\n- Set default messages\n- Show information, warning, errors\n- Set timeout for errors and warnings\n- Chain multiple messages\n\n## Installation\n```pip3 install ctkentrymsg```\n\n## Usage\n```\nentry = CTkEntryMsg(root,...)\n```\n\n## Basic Example\n```\nfrom ctkentrymsg import CTkEntryMsg\nfrom customtkinter import CTk, CTkLabel\n\nroot = CTk()\n\nroot.title('CTkEntryMsg Example')\n\nCTkLabel(root, text='Username', width=100).grid(\n row=0, column=0, sticky='nw', padx=(2,0), pady=(10,0))\n\nusername = CTkEntryMsg(\n root, \n default_msg='* letter,digits, special chars (min 8 chars)',\n msg_default_color='blue',\n highlight=True,\n width=300)\nusername.grid(row=0, column=1, sticky='ne', pady=(5,0), padx=(0,5))\n# showing an error\nusername.showerror(msg='Username cannot be blank')\n\nroot.mainloop()\n```\n**Output:**\n\n<p align=\"center\">\n <picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/shine-jayakumar/CTkEntryMsg/master/doc_images/basic_usage.png\">\n <img src=\"https://raw.githubusercontent.com/shine-jayakumar/CTkEntryMsg/master/doc_images/basic_usage.png\">\n </picture>\n</p>\n\n## Arguments\n| Argument | Description |\n| ------ | ------ |\n| master | root, tkinter.Frame or CTkFrame |\n| default_msg | optional default message to show under Entry widget |\n| msg_default_color | default message text color. Defaults to #000000 |\n| msg_warn_color | message text color for warnings. Defaults to #FC8309 |\n| msg_error_color | message text color for errors. Defaults to #FC0909 |\n| msg_font: tuple | message font. Defaults to ('Arial', 12)|\n| msg_pos (str) | place message above or below the entry. Valid values - 'top', 'bottom'. Defaults to 'bottom'. |\n| highlight | change entry widget's foreground color on warning or error. Default is True |\n| highlight_warn_color | foreground color for entry on warning. Defaults to #FAC36A |\n| highlight_error_color | foreground color for entry on error. Defaults to #FF9090 |\n| msg_timeout | global message timeout (in milliseconds) for warnings and errors. Defaults to 3000 ms |\n\n## Methods\n| Method | Description |\n| ------ | ------ |\n| .restore_msg() | Restores message to default state |\n| .restore_entry() | Restores entry widget to default state |\n| .showerror(msg,...) | Displays error |\n| .showwarn(msg,...) | Displays warning |\n| .msg_queue(messages) | Chains multiple messages |\n\n<br/>\n\n**Inherited methods from CTkEntry widget**\n| Method | Description |\n| ------ | ------ |\n| .configure(*args, **kwargs) | Configure CTkEntry widget's attribute. Ex: entry.configure(fg_color=\"#000000\")\n| .cget(attribute_name) | Returns value for attribute (passed as string) Ex: state = entry.cget(\"state\") |\n| .bind(*args, **kwargs) | Bind command function to event specified by sequence |\n| .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. |\n| .insert(index, string) | Inserts string before the character at the given index |\n| .get() | Returns current string in the entry. |\n| .focus() | Set the focus on the CTkEntry widget |\n| .focus_force() | Focuses a widget and the window it's in, immediately |\n| .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. |\n| .icursor(index) | Set the insertion cursor just before the character at the given index. |\n| .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. |\n| .select_from(index) | Sets the tk.ANCHOR index position to the character selected by index, and selects that character. |\n| .select_clear() | Clears the selection. If there isn't currently a selection, has no effect. |\n| .select_present() | If there is a selection, returns true, else returns false. |\n| .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. |\n| .select_to(index) | Selects all the text from the tk.ANCHOR position up to but not including the character at the given index. |\n| .xview(index) | Same as .xview(). This method is useful in linking the Entry widget to a horizontal scrollbar. |\n| .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. |\n| .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 \u201cpage\u201d to the right, and e.xview_scroll(4, tk.UNITS) would move the text four characters to the left. |\n\n# More Examples\n\n## Chaining Messages\nQueues the messages and shows them one after another, seperated at an interval specified in\n```timeout``` or ```msg_timeout``` argument.\n```\nentry = CTkEntryMsg(root, width=300)\nmessages = [\n ('error', 'An error message', 1000),\n ('warn', 'A warning message', 1000),\n ('error', 'Another error')\n]\nentry.msg_queue(messages)\n```\n## Persistent messages\nKeeps the message and the entry widget highlighted even after timeout.\n```\nentry = CTkEntryMsg(root, width=300)\nentry.showwarn(\n msg='This is a warning', \n persist_msg: bool = True, \n persist_highlight: bool = True)\n```\n## Setting Message Timeout\nSet a default timeout or message specific timeout\n```\n# timeout for all messages\nentry = CTkEntryMsg(root, ..., msg_timeout=2000)\n# this error is shown for 2 seconds\nentry.showwarn('This is an error')\n# this error is shown only for 1 second\nentry.showerror('This is an error', timeout=1000)\n```\n## Setting Attributes\n```\nentry = CTkEntryMsg(\n root, \n fg_color='black',\n text_color='white',\n width=300)\n```\nYou can also use .configure(...)\n```\nentry.configure(font=('Arial', 12), width=400,...)\n```\n\n\nChange Log\n==========\n\n[0.0.5] - 2024-01-03\n------------------\n- Added msg_pos parameter - placement of messages on top or bottom of the entry widget\n\n[0.0.4] - 2023-12-25\n------------------\n- Removed unused param from docstring\n\n[0.0.3] - 2023-12-25\n------------------\nBug fix:\n- added padding for warnings\n\n[0.0.2] - 2023-12-25\n------------------\nBug fix:\n- fixed packaging error\n\n[0.0.1] - 2023-12-25\n------------------\n- First Release\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "CTkEntry widget with message functionality",
"version": "0.0.5",
"project_urls": {
"Documentation": "https://github.com/shine-jayakumar/CTkEntryMsg",
"Homepage": "https://github.com/shine-jayakumar/CTkEntryMsg",
"Source": "https://github.com/shine-jayakumar/CTkEntryMsg"
},
"split_keywords": [
"ctkentrymsg",
"customtkinter",
"tkinter",
"ctkentry",
" ctkentry-show-message"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2713cb81676f5688291ad8f4d38b93ff2f739a99570aa99c32bf704936b73b1a",
"md5": "bf15f67c934f09dbd227996a2039044e",
"sha256": "c9de5ad9282ea775b4b5465547532e05cee1b37acf68ce0c7bbd236c29cbe82a"
},
"downloads": -1,
"filename": "ctkentrymsg-0.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bf15f67c934f09dbd227996a2039044e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 7835,
"upload_time": "2024-01-03T06:52:50",
"upload_time_iso_8601": "2024-01-03T06:52:50.359915Z",
"url": "https://files.pythonhosted.org/packages/27/13/cb81676f5688291ad8f4d38b93ff2f739a99570aa99c32bf704936b73b1a/ctkentrymsg-0.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a2a8d0157baeb12a90b8dd70e35f4ecf9166ba903063f3d61287804022e87c7c",
"md5": "098578f6e3b7863d553aaeaf5f1edf64",
"sha256": "cbfc5a47469d73ea981e8b3b3eada18f9cd352ebc3d378e38d1aa7adfa68d612"
},
"downloads": -1,
"filename": "ctkentrymsg-0.0.5.tar.gz",
"has_sig": false,
"md5_digest": "098578f6e3b7863d553aaeaf5f1edf64",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 8084,
"upload_time": "2024-01-03T06:52:51",
"upload_time_iso_8601": "2024-01-03T06:52:51.882866Z",
"url": "https://files.pythonhosted.org/packages/a2/a8/d0157baeb12a90b8dd70e35f4ecf9166ba903063f3d61287804022e87c7c/ctkentrymsg-0.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-03 06:52:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "shine-jayakumar",
"github_project": "CTkEntryMsg",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "ctkentrymsg"
}
JSON
