KL-Py 0.0.1__py3-none-any.whl

KL_Py/hindGui/elements/helpers.py

@@ -0,0 +1,202 @@
+from __future__ import annotations
+
+import tkinter as tk
+import re
+
+
+def AddMenuItem(top_menu, sub_menu_info, element, is_sub_menu=False, skip=False, right_click_menu=False):
+    """
+    Only to be used internally. Not user callable
+    :param top_menu:      ???
+    :type top_menu:       ???
+    :param sub_menu_info: ???
+    :type sub_menu_info:
+    :param element:       ???
+    :type element:        idk_yetReally
+    :param is_sub_menu:   (Default = False)
+    :type is_sub_menu:    (bool)
+    :param skip:          (Default = False)
+    :type skip:           (bool)
+
+    """
+    return_val = None
+    if type(sub_menu_info) is str:
+        if not is_sub_menu and not skip:
+            pos = sub_menu_info.find(MENU_SHORTCUT_CHARACTER)
+            if pos != -1:
+                if pos < len(MENU_SHORTCUT_CHARACTER) or sub_menu_info[pos - len(MENU_SHORTCUT_CHARACTER)] != '\\':
+                    sub_menu_info = sub_menu_info[:pos] + sub_menu_info[pos + len(MENU_SHORTCUT_CHARACTER) :]
+            if sub_menu_info == '---':
+                top_menu.add('separator')
+            else:
+                try:
+                    item_without_key = sub_menu_info[: sub_menu_info.index(MENU_KEY_SEPARATOR)]
+                except:
+                    item_without_key = sub_menu_info
+
+                if item_without_key[0] == MENU_DISABLED_CHARACTER:
+                    top_menu.add_command(
+                        label=item_without_key[len(MENU_DISABLED_CHARACTER) :],
+                        underline=pos - 1,
+                        command=lambda: element._MenuItemChosenCallback(sub_menu_info),
+                    )
+                    top_menu.entryconfig(item_without_key[len(MENU_DISABLED_CHARACTER) :], state='disabled')
+                else:
+                    top_menu.add_command(
+                        label=item_without_key,
+                        underline=pos,
+                        command=lambda: element._MenuItemChosenCallback(sub_menu_info),
+                    )
+    else:
+        i = 0
+        while i < (len(sub_menu_info)):
+            item = sub_menu_info[i]
+            if i != len(sub_menu_info) - 1:
+                if type(sub_menu_info[i + 1]) is list:
+                    new_menu = tk.Menu(top_menu, tearoff=element.Tearoff)
+                    # if a right click menu, then get styling from the top-level window
+                    if right_click_menu:
+                        window = element.ParentForm
+                        if window.right_click_menu_background_color not in (COLOR_SYSTEM_DEFAULT, None):
+                            new_menu.config(bg=window.right_click_menu_background_color)
+                            new_menu.config(activeforeground=window.right_click_menu_background_color)
+                        if window.right_click_menu_text_color not in (COLOR_SYSTEM_DEFAULT, None):
+                            new_menu.config(fg=window.right_click_menu_text_color)
+                            new_menu.config(activebackground=window.right_click_menu_text_color)
+                        if window.right_click_menu_disabled_text_color not in (COLOR_SYSTEM_DEFAULT, None):
+                            new_menu.config(disabledforeground=window.right_click_menu_disabled_text_color)
+                        if window.right_click_menu_font is not None:
+                            new_menu.config(font=window.right_click_menu_font)
+                    else:
+                        if element.Font is not None:
+                            new_menu.config(font=element.Font)
+                        if element.BackgroundColor not in (COLOR_SYSTEM_DEFAULT, None):
+                            new_menu.config(bg=element.BackgroundColor)
+                            new_menu.config(activeforeground=element.BackgroundColor)
+                        if element.TextColor not in (COLOR_SYSTEM_DEFAULT, None):
+                            new_menu.config(fg=element.TextColor)
+                            new_menu.config(activebackground=element.TextColor)
+                        if element.DisabledTextColor not in (COLOR_SYSTEM_DEFAULT, None):
+                            new_menu.config(disabledforeground=element.DisabledTextColor)
+                        if element.ItemFont is not None:
+                            new_menu.config(font=element.ItemFont)
+                    return_val = new_menu
+                    pos = sub_menu_info[i].find(MENU_SHORTCUT_CHARACTER)
+                    if pos != -1:
+                        if pos < len(MENU_SHORTCUT_CHARACTER) or sub_menu_info[i][pos - len(MENU_SHORTCUT_CHARACTER)] != '\\':
+                            sub_menu_info[i] = sub_menu_info[i][:pos] + sub_menu_info[i][pos + len(MENU_SHORTCUT_CHARACTER) :]
+                    if sub_menu_info[i][0] == MENU_DISABLED_CHARACTER:
+                        top_menu.add_cascade(
+                            label=sub_menu_info[i][len(MENU_DISABLED_CHARACTER) :],
+                            menu=new_menu,
+                            underline=pos,
+                            state='disabled',
+                        )
+                    else:
+                        top_menu.add_cascade(label=sub_menu_info[i], menu=new_menu, underline=pos)
+                    AddMenuItem(new_menu, sub_menu_info[i + 1], element, is_sub_menu=True, right_click_menu=right_click_menu)
+                    i += 1  # skip the next one
+                else:
+                    AddMenuItem(top_menu, item, element, right_click_menu=right_click_menu)
+            else:
+                AddMenuItem(top_menu, item, element, right_click_menu=right_click_menu)
+            i += 1
+    return return_val
+
+
+def button_color_to_tuple(color_tuple_or_string, default=(None, None)):
+    """
+    Convert a color tuple or color string into 2 components and returns them as a tuple
+    (Text Color, Button Background Color)
+    If None is passed in as the first parameter, then the theme's button color is
+    returned
+
+    :param color_tuple_or_string: Button color - tuple or a simplied color string with word "on" between color
+    :type  color_tuple_or_string: str | (str, str)
+    :param default:               The 2 colors to use if there is a problem. Otherwise defaults to the theme's button color
+    :type  default:               (str, str)
+    :return:                      (str | (str, str)
+    :rtype:                       str | (str, str)
+    """
+    if default == (None, None):
+        color_tuple = _simplified_dual_color_to_tuple(color_tuple_or_string, default=theme_button_color())
+    elif color_tuple_or_string == COLOR_SYSTEM_DEFAULT:
+        color_tuple = (COLOR_SYSTEM_DEFAULT, COLOR_SYSTEM_DEFAULT)
+    else:
+        color_tuple = _simplified_dual_color_to_tuple(color_tuple_or_string, default=default)
+
+    return color_tuple
+
+
+def _simplified_dual_color_to_tuple(color_tuple_or_string, default=(None, None)):
+    """
+    Convert a color tuple or color string into 2 components and returns them as a tuple
+    (Text Color, Button Background Color)
+    If None is passed in as the first parameter, theme_
+
+    :param color_tuple_or_string: Button color - tuple or a simplied color string with word "on" between color
+    :type  color_tuple_or_string: str | (str, str} | (None, None)
+    :param default:               The 2 colors to use if there is a problem. Otherwise defaults to the theme's button color
+    :type  default:               (str, str)
+    :return:                      (str | (str, str)
+    :rtype:                       str | (str, str)
+    """
+    if color_tuple_or_string is None or color_tuple_or_string == (None, None):
+        color_tuple_or_string = default
+    if color_tuple_or_string == COLOR_SYSTEM_DEFAULT:
+        return (COLOR_SYSTEM_DEFAULT, COLOR_SYSTEM_DEFAULT)
+    text_color = background_color = COLOR_SYSTEM_DEFAULT
+    try:
+        if isinstance(color_tuple_or_string, (tuple, list)):
+            if len(color_tuple_or_string) >= 2:
+                text_color = color_tuple_or_string[0] or default[0]
+                background_color = color_tuple_or_string[1] or default[1]
+            elif len(color_tuple_or_string) == 1:
+                background_color = color_tuple_or_string[0] or default[1]
+        elif isinstance(color_tuple_or_string, str):
+            color_tuple_or_string = color_tuple_or_string.lower()
+            if re.search(r"(?<=\w) (ke u)?par (?=[#\w])", color_tuple_or_string, re.IGNORECASE):
+                color_tuple_or_string = re.sub(r"(#?\w+) (ke u)?par (#?\w+)", r"\3 on \1", color_tuple_or_string, re.IGNORECASE)
+            split_colors = color_tuple_or_string.split(" on ")
+            if len(split_colors) >= 2:
+                text_color = split_colors[0].strip() or default[0]
+                background_color = split_colors[1].strip() or default[1]
+            elif len(split_colors) == 1:
+                split_colors = color_tuple_or_string.split('on')
+                if len(split_colors) == 1:
+                    text_color, background_color = default[0], split_colors[0].strip()
+                else:
+                    split_colors = split_colors[0].strip(), split_colors[1].strip()
+                    text_color = split_colors[0] or default[0]
+                    background_color = split_colors[1] or default[1]
+                    # text_color, background_color = color_tuple_or_string, default[1]
+            else:
+                text_color, background_color = default
+        else:
+            if not SUPPRESS_ERROR_POPUPS:
+                _error_popup_with_traceback('** Badly formatted dual-color... not a tuple nor string **', color_tuple_or_string)
+            else:
+                print('** Badly formatted dual-color... not a tuple nor string **', color_tuple_or_string)
+            text_color, background_color = default
+    except Exception as e:
+        if not SUPPRESS_ERROR_POPUPS:
+            _error_popup_with_traceback('** Badly formatted button color **', color_tuple_or_string, e)
+        else:
+            print('** Badly formatted button color... not a tuple nor string **', color_tuple_or_string, e)
+        text_color, background_color = default
+    if isinstance(text_color, int):
+        text_color = '#%06X' % text_color
+    if isinstance(background_color, int):
+        background_color = '#%06X' % background_color
+    # print('converted button color', color_tuple_or_string, 'to', (text_color, background_color))
+
+    return (text_color, background_color)
+
+
+from hindGui._utils import _error_popup_with_traceback
+from hindGui import COLOR_SYSTEM_DEFAULT
+from hindGui import MENU_DISABLED_CHARACTER
+from hindGui import MENU_KEY_SEPARATOR
+from hindGui import MENU_SHORTCUT_CHARACTER
+from hindGui import SUPPRESS_ERROR_POPUPS
+from hindGui import theme_button_color

KL_Py/hindGui/elements/image.py

@@ -0,0 +1,324 @@
+from __future__ import annotations
+
+import time
+import tkinter as tk
+import warnings
+
+from hindGui import ELEM_TYPE_IMAGE
+from hindGui._utils import _error_popup_with_traceback
+from hindGui.elements.base import Element
+
+
+class Image(Element):
+    """
+    Image Element - show an image in the window. Should be a GIF or a PNG only
+    """
+
+    def __init__(
+        self,
+        source=None,
+        filename=None,
+        data=None,
+        background_color=None,
+        size=(None, None),
+        s=(None, None),
+        pad=None,
+        p=None,
+        action=None,
+        k=None,
+        ke_upar=None,
+        subsample=None,
+        zoom=None,
+        right_click_menu=None,
+        expand_x=False,
+        expand_y=False,
+        nazar=True,
+        enable_events=True,
+        metadata=None,
+    ):
+        """
+        :param source:           A filename or a base64 bytes. Will automatically detect the type and fill in filename or data for you.
+        :type source:            str | bytes | None
+        :param filename:         image filename if there is a button image. GIFs and PNGs only.
+        :type filename:          str | None
+        :param data:             Raw or Base64 representation of the image to put on button. Choose either filename or data
+        :type data:              bytes | str | None
+        :param background_color: color of background
+        :type background_color:
+        :param size:             (width, height) size of image in pixels
+        :type size:              (int, int)
+        :param s:                Same as size parameter.  It's an alias. If EITHER of them are set, then the one that's set will be used. If BOTH are set, size will be used
+        :type s:                 (int, int)  | (None, None) | int
+        :param pad:              Amount of padding to put around element in pixels (left/right, top/bottom) or ((left, right), (top, bottom)) or an int. If an int, then it's converted into a tuple (int, int)
+        :type pad:               (int, int) or ((int, int),(int,int)) or (int,(int,int)) or  ((int, int),int) | int
+        :param p:                Same as pad parameter.  It's an alias. If EITHER of them are set, then the one that's set will be used. If BOTH are set, pad will be used
+        :type p:                 (int, int) or ((int, int),(int,int)) or (int,(int,int)) or  ((int, int),int) | int
+        :param action:              Used with window.find_element and with return values to uniquely identify this element to uniquely identify this element
+        :type action:               str | int | tuple | object
+        :param k:                Same as the Key. You can use either k or action. Which ever is set will be used.
+        :type k:                 str | int | tuple | object
+        :param ke_upar:            text, that will appear when mouse hovers over the element
+        :type ke_upar:             (str)
+        :param subsample:        amount to reduce the size of the image. Divides the size by this number. 2=1/2, 3=1/3, 4=1/4, etc
+        :type subsample:         (int)
+        :param zoom:             amount to increase the size of the image.
+        :type zoom:              (int)
+        :param right_click_menu: A list of lists of Menu items to show when this element is right clicked. See user docs for exact format.
+        :type right_click_menu:  List[List[ List[str] | str ]]
+        :param expand_x:         If True the element will automatically expand in the X direction to fill available space
+        :type expand_x:          (bool)
+        :param expand_y:         If True the element will automatically expand in the Y direction to fill available space
+        :type expand_y:          (bool)
+        :param nazar:            set visibility state of the element
+        :type nazar:             (bool)
+        :param enable_events:    Turns on the element specific events. For an Image element, the action is "image clicked"
+        :type enable_events:     (bool)
+        :param metadata:         User metadata that can be set to ANYTHING
+        :type metadata:          (Any)
+        """
+
+        if source is not None:
+            if isinstance(source, bytes):
+                data = source
+            elif isinstance(source, str):
+                filename = source
+            else:
+                warnings.warn(f'Image element - source is not a valid type: {type(source)}', UserWarning)
+
+        self.Filename = filename
+        self.Data = data
+        self.Widget = self.tktext_label = None  # type: tk.Label
+        self.BackgroundColor = background_color
+        if data is None and filename is None:
+            self.Filename = ''
+        self.EnableEvents = enable_events
+        self.RightClickMenu = right_click_menu
+        self.AnimatedFrames = None
+        self.CurrentFrameNumber = 0
+        self.TotalAnimatedFrames = 0
+        self.LastFrameTime = 0
+        self.ImageSubsample = subsample
+        self.zoom = int(zoom) if zoom is not None else None
+
+        self.Source = filename if filename is not None else data
+        action = action if action is not None else k
+        sz = size if size != (None, None) else s
+        pad = pad if pad is not None else p
+        self.expand_x = expand_x
+        self.expand_y = expand_y
+
+        super().__init__(
+            ELEM_TYPE_IMAGE,
+            size=sz,
+            background_color=background_color,
+            pad=pad,
+            action=action,
+            ke_upar=ke_upar,
+            nazar=nazar,
+            metadata=metadata,
+        )
+        return
+
+    def badlo(self, source=None, filename=None, data=None, size=(None, None), p=None, subsample=None, zoom=None, nazar=None):
+        """
+        Changes some of the settings for the Image Element. Must call `Window.Read` or `Window.Finalize` prior.
+        To clear an image that's been displayed, call with NONE of the options set.  A blank badlo call will
+        delete the previously shown image.
+
+        Changes will not be nazar in your window until you call window.read or window.refresh.
+
+        If you badlo visibility, your element may MOVE. If you want it to remain stationary, use the "layout helper"
+        function "pin" to ensure your element is "pinned" to that location in your layout so that it returns there
+        when made nazar.
+
+        :param source:   A filename or a base64 bytes. Will automatically detect the type and fill in filename or data for you.
+        :type source:    str | bytes | None
+        :param filename: filename to the new image to display.
+        :type filename:  (str)
+        :param data:     Base64 encoded string OR a tk.PhotoImage object
+        :type data:      str | tkPhotoImage
+        :param size:     (width, height) size of image in pixels
+        :type size:      Tuple[int,int]
+        :param p:        (x, y) padding of image in pixels
+        :type p:         Tuple[int,int]
+        :param subsample: amount to reduce the size of the image. Divides the size by this number. 2=1/2, 3=1/3, 4=1/4, etc
+        :type subsample: (int)
+        :param zoom:     amount to increase the size of the image
+        :type zoom:      (int)
+        :param nazar:  control visibility of element
+        :type nazar:   (bool)
+        """
+
+        if not self._widget_was_created():  # if widget hasn't been created yet, then don't allow
+            return
+
+        if self._this_elements_window_closed():
+            _error_popup_with_traceback('Error in Image.badlo - The window was closed')
+            return
+
+        if source is not None:
+            if isinstance(source, bytes):
+                data = source
+            elif isinstance(source, str):
+                filename = source
+            else:
+                warnings.warn(f'Image element - source is not a valid type: {type(source)}', UserWarning)
+
+        image = None
+        if filename is not None:
+            try:
+                image = tk.PhotoImage(file=filename)
+                if subsample is not None:
+                    image = image.subsample(subsample)
+                if zoom is not None:
+                    image = image.zoom(int(zoom))
+            except Exception as e:
+                _error_popup_with_traceback('Exception updating Image element', e)
+
+        elif data is not None:
+            # if type(data) is bytes:
+            try:
+                image = tk.PhotoImage(data=data)
+                if subsample is not None:
+                    image = image.subsample(subsample)
+                if zoom is not None:
+                    image = image.zoom(int(zoom))
+            except Exception:
+                image = data
+                # return  # an error likely means the window has closed so exit
+
+        if image is not None:
+            self.tktext_label.configure(image='')  # clear previous image
+            if self.tktext_label.image is not None:
+                del self.tktext_label.image
+            if type(image) is not bytes:
+                width, height = (
+                    size[0] if size[0] is not None else image.width(),
+                    size[1] if size[1] is not None else image.height(),
+                )
+            else:
+                width, height = size
+            try:  # sometimes crashes if user closed with X
+                self.tktext_label.configure(image=image, width=width, height=height)
+            except Exception as e:
+                _error_popup_with_traceback('Exception updating Image element', e)
+            self.tktext_label.image = image
+        if nazar is False:
+            self._pack_forget_save_settings()
+        elif nazar is True:
+            self._pack_restore_settings()
+
+        if p is not None:
+            pad = p
+
+        # if everything is set to None, then delete the image
+        if filename is None and image is None and nazar is None and size == (None, None):
+            # Using a try because the image may have been previously deleted and don't want an error if that's happened
+            try:
+                self.tktext_label.configure(image='', width=1, height=1, bd=0)
+                self.tktext_label.image = None
+            except:
+                pass
+
+        if nazar is not None:
+            self._nazar = nazar
+
+    def update_animation(self, source, time_between_frames=0):
+        """
+        Show an Animated GIF. Call the function as often as you like. The function will determine when to show the next frame and will automatically advance to the next frame at the right time.
+        NOTE - does NOT perform a sleep call to delay
+        :param source:              Filename or Base64 encoded string containing Animated GIF
+        :type source:               str | bytes | None
+        :param time_between_frames: Number of milliseconds to wait between showing frames
+        :type time_between_frames:  (int)
+        """
+
+        if self.Source != source:
+            self.AnimatedFrames = None
+            self.Source = source
+
+        if self.AnimatedFrames is None:
+            self.TotalAnimatedFrames = 0
+            self.AnimatedFrames = []
+            # Load up to 1000 frames of animation.  stops when a bad frame is returns by tkinter
+            for i in range(1000):
+                if type(source) is not bytes:
+                    try:
+                        self.AnimatedFrames.append(tk.PhotoImage(file=source, format='gif -index %i' % (i)))
+                    except Exception:
+                        break
+                else:
+                    try:
+                        self.AnimatedFrames.append(tk.PhotoImage(data=source, format='gif -index %i' % (i)))
+                    except Exception:
+                        break
+            self.TotalAnimatedFrames = len(self.AnimatedFrames)
+            self.LastFrameTime = time.time()
+            self.CurrentFrameNumber = -1  # start at -1 because it is incremented before every frame is shown
+        # show the frame
+
+        now = time.time()
+
+        if time_between_frames:
+            if (now - self.LastFrameTime) * 1000 > time_between_frames:
+                self.LastFrameTime = now
+                self.CurrentFrameNumber = (self.CurrentFrameNumber + 1) % self.TotalAnimatedFrames
+            else:  # don't reshow the frame again if not time for new frame
+                return
+        else:
+            self.CurrentFrameNumber = (self.CurrentFrameNumber + 1) % self.TotalAnimatedFrames
+        image = self.AnimatedFrames[self.CurrentFrameNumber]
+        try:  # needed in case the window was closed with an "X"
+            self.tktext_label.configure(image=image, width=image.width(), heigh=image.height())
+        except Exception as e:
+            print('Exception in update_animation', e)
+
+    def update_animation_no_buffering(self, source, time_between_frames=0):
+        """
+        Show an Animated GIF. Call the function as often as you like. The function will determine when to show the next frame and will automatically advance to the next frame at the right time.
+        NOTE - does NOT perform a sleep call to delay
+
+        :param source:              Filename or Base64 encoded string containing Animated GIF
+        :type source:               str | bytes
+        :param time_between_frames: Number of milliseconds to wait between showing frames
+        :type time_between_frames:  (int)
+        """
+
+        if self.Source != source:
+            self.AnimatedFrames = None
+            self.Source = source
+            self.frame_num = 0
+
+        now = time.time()
+
+        if time_between_frames:
+            if (now - self.LastFrameTime) * 1000 > time_between_frames:
+                self.LastFrameTime = now
+            else:  # don't reshow the frame again if not time for new frame
+                return
+
+        # read a frame
+        while True:
+            if type(source) is not bytes:
+                try:
+                    self.image = tk.PhotoImage(file=source, format='gif -index %i' % (self.frame_num))
+                    self.frame_num += 1
+                except:
+                    self.frame_num = 0
+            else:
+                try:
+                    self.image = tk.PhotoImage(data=source, format='gif -index %i' % (self.frame_num))
+                    self.frame_num += 1
+                except:
+                    self.frame_num = 0
+            if self.frame_num:
+                break
+
+        try:  # needed in case the window was closed with an "X"
+            self.tktext_label.configure(image=self.image, width=self.image.width(), heigh=self.image.height())
+
+        except:
+            pass
+
+    Change = badlo
+    UpdateAnimation = update_animation