Skip to content

Latest commit

 

History

History
794 lines (586 loc) · 41.9 KB

DOCUMENTATION_en.md

File metadata and controls

794 lines (586 loc) · 41.9 KB
Raw

中文说明 Doc. | Chinese Doc.

Back to the Top | Examples | Parameter Explanation | Whats New ?

Importing & Installation

  • Installation
pip install tkchart
  • Importing
import tkchart

Parameter Overview

To display data using tkchart you need to do 3 main tasks

  1. Creating a Line Chart
  2. Creating a Line
  3. Display of data

1 . Creating a Line Chart

Creating a Line | Display of data

linechart = tkchart.LineChart()

Parameters

Parameter Required / Optional Description Types Example Value(s)
master Required Master Widget for LineChart widget widget
y_axis_values Required Minimum and maximum values for y-axis tuple[[int | float], ...] (-1000, 1000), ...
x_axis_values Required Values for x-axis tuple[any, ...] (1, 2, 3, 4, 5), ...
width Optional Width of the chart int 300, ...
height Optional Height of the chart int 100, ...
axis_size Optional Size of the axis int 1<=
axis_color Optional Color of the axis str "#2C2C2C" , "blue", ...
bg_color Optional Background color of the chart str "#191919", ...
fg_color Optional Foreground color of the chart str "#191919", ...
data_font_style Optional Font style for data labels tuple[str, int, str] ("arial", 9, "bold"), ...
axis_font_style Optional Font style for axis labels tuple[str, int, str] ("arial", 8, "normal"), ...
x_axis_data Optional Data label for x-axis str "X", ...
y_axis_data Optional Value for y-axi data label any "Y", ...
x_axis_data_font_color Optional Font color for x-axis data label str "#707070", ...
y_axis_data_font_color Optional Font color for y-axis data label str "#707070", ...
x_axis_data_position Optional Position of x-axis data label str ("top", "side") "top"
y_axis_data_position Optional Position of y-axis data label str ("top", "side") "top"
x_axis_section_count Optional Number of sections on the x-axis int 0<=
y_axis_section_count Optional Number of sections on the y-axis int 0<=
x_axis_label_count Optional Number of x-axis labels int 0<=
y_axis_label_count Optional Number of y-axis labels int 1<=
x_axis_font_color Optional Font color for x-axis labels str "#606060", ...
y_axis_font_color Optional Font color for y-axis labels str "#606060", ...
x_axis_section_style Optional Style of sections on the x-axis str ("normal", "dashed") "normal"
y_axis_section_style Optional Style of sections on the y-axis str ("normal", "dashed") "normal"
x_axis_section_style_type Optional Style type for sections on the x-axis tuple[int, int] (100, 50) , (50,50), ...
y_axis_section_style_type Optional Style type for sections on the y-axis tuple[int, int] (100, 50)
x_axis_section_color Optional Color of sections on the x-axis str "#2C2C2C", ...
y_axis_section_color Optional Color of sections on the y-axis str "#2C2C2C"
y_axis_precision Optional Precision for y-axis values int 0<=
x_axis_display_values_indices Optional Indices of values to display on the x-axis tuple[int, ...] (0, 1, 2, 3, 4, 5), ...
x_axis_point_spacing Optional Width of lines int | str "auto" "auto"
1<=
x_space Optional Space between x-axis and chart area int 0<=
y_space Optional Space between y-axis and chart area int 0<=
pointer_state Optional State of the pointer str ("enabled", "disabled") "disabled"
pointing_callback_function Optional Callback function for pointer callable function(*args)
function(x, y)
pointer_color Optional Color of the pointer str "#606060", ...
pointing_values_precision Optional Precision for pointing values int 0<=
pointer_lock Optional State of pointer lock str ("enabled", "disabled") "enabled"
pointer_size Optional Size of the pointer int 1<=

Methods

Method Description Supported / Required Parameters Return Type
configure Change LineChart attributes All attributes except for master None
show_data Display data data: list
line: tkchart.Line		 None
place Place LineChart x: int
y: int
rely: float or int
relx: float or int
anchor: str		 None
pack Pack LineChart pady: int
padx: int
before: widget
after: widget
side: str
anchor: str		 None
grid Grid LineChart column: int
columnspan: int
padx: int
pady: int
row: int
rowspan: int
sticky: str		 None
place_forget Place forget the chart - None
pack_forget Pack forget the chart - None
grid_forget Grid forget the chart - None
set_lines_visibility Change the visibility of all the lines state: bool None
set_line_visibility Change the visibility of a specific line line: tkchart.Line
state: bool		 None
get_line_visibility Get the visibility of a specific line line: tkchart.Line bool
reset Reset line chart - None
cget Get the value of the specified parameter attribute_name: str | "__all__" any
place_info Get info about place attribute_name: str | "__all__" any
pack_info Get info about pack attribute_name: str | "__all__" any
grid_info Get info about grid attribute_name: str | "__all__" any
get_line_area Get the are of specific line line: tkchart.Line float
get_lines_area Get the are of all lines - float
clear_data Clears the data for all lines within the chart, ensuring that only the most recent visible data points are retained. If the total data points exceed the maximum visible points, the older data is removed from each line's data. This method ensures that the chart displays only the relevant portion of data based on the maximum visible range. - None
destroy Destroy the chart - None

2 . Creating a Line

Creating a Line Chart | Display of data

line = tkchart.Line()

Parameters

Parameter Name Required / Optional Description Types Example Value(s)
master Required Master of the line tkchart.Line LineChart obj
color Optional Color of the line str "#768df1"
size Optional Size of the line int 1<=
style Optional Style of the line str ("normal", "dashed", "dotted") "normal"
style_type Optional Style type for the line tuple[int, int] (10, 5),...
point_highlight Optional State of point highlighting str ("enabled", "disabled") "disabled"
point_highlight_size Optional Size of the highlighted point int 1<=
point_highlight_color Optional Color of the highlighted point str "#768df1"
fill Optional State of filling str ("enabled", "disabled") "disabled"
fill_color Optional Color of the fill str "#5d6db6"

Methods

Method Description Supported Parameters Return Type
configure Change LineChart attributes All attributes except for master None
cget Get the value of the specified parameter attribute_name: str | "__all__" any
reset reset line object - None
set_visible change the visibility of the line state: bool None
get_visibility get the visibility of the line - bool
clear_data Clears the data for a specific line, ensuring that only the most recent visible data points are retained. If the line's data exceeds the maximum visible points, the older data is trimmed. This method allows each line to independently clean its data, ensuring it remains within the visible range. - None
destroy Destroy the line - None

3 . Display of Data

Creating a Line Chart | Creating a Line

import tkinter as tk 
import ctkchart 
import random 

#root 
root = tk.Tk() 
root.configure(bg="#151515") 

#creating a chart 
chart = tkchart.LineChart(
    master=root, 
    x_axis_values = (1, 2, 3, 4, 5, 6, 7, 8, 9, 10), 
    y_axis_values = (-100,100)
) 
chart.pack() 

#creating a line 
line = tkchart.Line(master=chart) 

data = [x for x in range(-100,101)] #values -100 to 100 
#dipslay data (random) 
def loop(): 
    chart.show_data(line=line, data=random.choices(data, k=1)) 
    root.after(500, loop) 
loop() 

root.mainloop()
output.mp4

Back to the Top | Usage Guide | Examples | Whats New ?

Parameter Explanation

CTkLineChart

  • y_axis_values

    y_axis_values is a tuple that containing two numeric values for the y-axis. The first value (index 0) represents the starting value of the y-axis, and the second value (index 1) represents the end value of the y-axis. This tuple defines the range of values displayed along the y-axis on chart.

  • x_axis_values

    x_axis_values is a collection of values that can include any data type. These values are assigned to the x-axis, starting from index 0 and continuing to the last index of the x_axis_values tuple. Each value in the tuple corresponds to a point along the x-axis in chart.

    chart = tkchart.LineChart(
    master=any_widget
    x_axis_values=(2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025), 
    y_axis_values=(-100, 100) 
)

  • x_axis_data

    refers to the value type displayed in the x-axis of a chart. Note: "X" is the default value.

  • y_axis_data

    refers to the value type displayed in the y-axis of a chart. Note: "Y" is the default value.

  • x_axis_data_font_color

    refers to the font color applied to the label representing the data type on x-axis of a chart.

  • y_axis_data_font_color

    refers to the font color applied to the label representing the data type on y-axis of a chart.

  • data_font_style

    refers to the font style applied to the labels representing the data types on both the x-axis and y-axis of a chart.

    chart = tkchart.LineChart(
    master=any_widget, 
    x_axis_values=(2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025), 
    y_axis_values=(-100, 100), 
    y_axis_data="Y data" , 
    x_axis_data="X data", 
    x_axis_data_font_color="#ff0000", 
    y_axis_data_font_color="#00ff00", 
    data_font_style=("arial", 15, "underline") 
)

  • x_axis_label_count

    When you have a set of x-axis labels, such as years from 2018 to 2025, normally all these labels are shown. But sometimes you might want to show only a few of them for better clarity.
    For instance, if you set the x_axis_label_count to 4, it means you want to display only 4 labels instead of all 8. So, the chart will automatically skip some labels to fit your specified count.
    Note: len(x_axis_values) is the default value.
    In other words, adjusting the x_axis_label_count allows you to control how many labels appear on the x-axis, making your visualization cleaner and easier to understand.

    • if there are 9 labels you can limit it to : 3, 1, 0.
    • if there are 20 labels you can limit it to : 10, 5, 4, 2, 1, 0.
    • if there are 15 labels you can limit it to : 5, 3, 1, 0.
    In some cases, using the x_axis_label_count parameter might not be sufficient for your needs. In such situations, you can utilize the x_axis_display_values_indices parameter to precisely control which values are displayed on the x-axis.

  • y_axis_label_count

    By default, if you set the y-axis values to range from -100 to 100, only the extreme values (-100 and 100) will be displayed on the y-axis. However, you have the option to adjust the number of labels displayed using the y_axis_label_count parameter.
    For example, if you set y_axis_label_count to 3, the system will divide the y-axis range (-100 to 100) into equal intervals and display labels at those intervals. So, for this case, with a label count of 3, you might see labels at -100, 0, and 100.
    In summary, adjusting the y_axis_label_count parameter allows you to control the number of labels displayed on the y-axis, providing flexibility in customizing the visualization based on your preferences and requirements.

    chart = tkchart.LineChart(
    master=any_widget, 
    x_axis_values=(2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025), 
    y_axis_values=(-100, 100), 
    x_axis_label_count=4, 
    y_axis_label_count=10, 
)

  • x_axis_display_values_indices

    Let's say you have a set of x-axis values representing years from 2018 to 2025: (2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025). Normally, all these values would be displayed on the x-axis.
    However, there might be cases where you only want to display specific years rather than all of them. In such situations, you can use the x_axis_display_values_indices parameter to control which values are shown on the x-axis.
    For example, if you only want to display the years 2019, 2022, and 2025, you can specify their indices in the x_axis_display_values_indices parameter. So, if the index of 2919 is 1, 2022 is 4, and 2025 is 7 (assuming 0-based indexing), you would set x_axis_display_values_indices to (1, 4, 7).
    This way, by setting the indices of the values you want to display, you have precise control over which values appear on the x-axis in your visualization, allowing you to tailor it according to your specific requirements.

    chart = tkchart.LineChart(
    master=any_widget, 
    x_axis_values=(2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025), 
    y_axis_values=(-100, 100), 
    x_axis_display_values_indices=(1, 4, 7)
)

  • x_axis_data_position

    The x_axis_data_position parameter determines the position of the x data label. It has two

    supported values:

    • "top"
    • "side"

    Note: "top" is the default position

  • y_axis_data_position

    The y_axis_data_position parameter determines the position of the x data label. It has two

    supported values:

    • "top"
    • "side"

    Note: "top" is the default position

    Choosing between "top" and "side" determines whether the data labels are placed horizontally above the data points or vertically beside them, respectively. This parameter allows you to customize the layout of your chart according to your preferences and available space.

    chart = tkchart.LineChart(
    master=any_widget, 
    x_axis_values=(2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025), 
    y_axis_values=(-100, 100), 
    x_axis_data_position="side", 
    y_axis_data_position="top" 
)

  • y_axis_precision

    The y_axis_precision parameter controls the number of decimal places displayed for the values on the y-axis.
    Note: 1 is the deafault precion
    For example:

    • If you set y_axis_precision to 0, the values on the y-axis will be displayed as whole numbers.
    • If you set y_axis_precision to 1, the values on the y-axis will be displayed with one decimal place.
    • If you set y_axis_precision to 2, the values on the y-axis will be displayed with two decimal places.

    And so on :

    • Adjusting the y_axis_precision parameter allows you to control the level of precision for the y-axis values in your chart. This parameter is particularly useful when dealing with data that requires specific precision or when you want to improve the readability of the chart by reducing the number of decimal places displayed.
    chart = tkchart.LineChart(
    master=any_widget, 
    x_axis_values=(2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025), 
    y_axis_values=(-100, 100), 
    y_axis_label_count=12, 
    y_axis_precision=4, 
)

  • axis_font_style

    refers to font style of the x and y axis values

  • x_axis_font_color

    refers to color of x axis values

  • y_axis_font_color

    refers to color of y axis values

    chart = tkchart.LineChart(
    master=any_widget, 
    x_axis_values=(2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025), 
    y_axis_values=(-100, 100), 
    x_axis_font_color="#00FF00", 
    y_axis_font_color="#FF0000", 
    axis_font_style=("arial", 13, "bold") 
)

  • x_axis_section_count

    The x_axis_section_count parameter defines the number of sections or intervals into which the x-axis range will be divided in a chart.
    Here's a clearer breakdown :
    • Let's say you have a range of values on the x-axis, such as years from 2018 to 2025. By default, this range might be represented as a continuous line without any specific sections or intervals marked.
    • However, if you set x_axis_section_count to a value, such as 8, it means you want to divide this x-axis range into equally spaced sections or intervals. Each section will represent a subset of the total x-axis range.
    • Adjusting the x_axis_section_count parameter allows you to control the granularity of the x-axis in your chart, making it easier for viewers to interpret the data and identify trends within specific intervals.

  • y_axis_section_count

    The y_axis_section_count parameter defines the number of sections or intervals into which the y-axis range will be divided in a chart.
    refer : x_axis_section_count for more...

  • x_axis_section_color

    refers to color of y axis sections

  • y_axis_section_color

    refers to color of x axis sections

    chart = tkchart.LineChart(
    master=any_widget, 
    x_axis_section_count=8, 
    y_axis_section_count=5, 
    x_axis_section_color="#2C2C2C", 
    y_axis_section_color="#2C2C2C" 
)

  • x_axis_section_style

    x_axis_section_style parameter allows you to define the visual style of the sections along the x-axis in a chart.

    • Supported styles:
      • "dashed": When you set x_axis_section_style to "dashed", the sections along the x-axis are displayed using dashed lines.
      • "normal": Conversely, when x_axis_section_style is set to "normal", the sections along the x-axis are displayed using solid lines.

    Note: "normal" is default style.

  • x_axis_section_style_type

    The x_axis_section_style_type parameter is a tuple that contains two integer values, specifying the style of the dashes used when the x_axis_section_style is set to "dashed".
    For example:

    • If you set x_axis_section_style_type to (20, 10), it means :
      • The width of each dash is 20 pixels.
      • The spacing between dashes is 10 pixels.

    These values determine the visual appearance of the dashed lines or markers used to represent the sections along the x-axis. Adjusting these values allows you to customize the appearance of the dashed sections according to your preferences or the requirements of your visualization.

  • y_axis_section_style_type

    working same as x_axis_section_style_type, refer x_axis_section_style_type for more

    chart = tkchart.LineChart(
    master=any_widget, 
    x_axis_section_count=8, 
    y_axis_section_count=5, 
    x_axis_section_style="dashed", 
    x_axis_section_style_type=(20,10), 
    y_axis_section_style="dashed", 
    y_axis_section_style_type=(20,10), 
)

  • x_axis_point_spacing

    The x_axis_point_spacing parameter allows your to manually set the spacing between points on the x-axis, typically measured in pixels. However, if you do not manually set this parameter, it is automatically calculated based on the length of x_axis_values.
    Note: "auto" is the default value.

    • after configure specific value to x_axis_point_spacing, you can reset value by configure it as "auto" for set default value.

    ``` python chart.configure(x_axis_point_spacing = "auto") ``` 
    chart = tkchart.LineChart(
    master=any_widget, 
    x_axis_point_spacing="auto" 
)

    The x_axis_point_spacing parameter is automatically calculated based on the length of the x_axis_values tuple. This means that the spacing between points on the x-axis is determined by dividing the width of the chart by the length of the x_axis_values list.

    When you set the x_axis_point_spacing parameter to a specific value, such as 40, it means that you have manually specified the spacing between points on the x-axis to be 40 units (e.g., pixels). In this case, the chart will use the user-defined spacing of 40 units between each point on the x-axis, regardless of the length of the x_axis_values tuple.

    chart = tkchart.LineChart(
    master=any_widget, 
    x_axis_point_spacing=40 
)

CTkLine

  • color

    refers to color of line.

  • size

    refers to size(thickness) of line.
    Note: 1 is the default size 

    line = tkchart.Line(
    master=chart, 
    color="#30ACC7", 
    size=5 
)

  • style

    style parameter allows you to define the visual style of the line.

    • supported styles:
      • "dashed": When you set style to "dashed", the line is displayed as dashed line.
      • "dotted": When you set style to "dotted", the line is displayed as dotted line.
      • "normal": When you set style to "normal", the line is displayed as solid line.

    Note: "normal" is the default style.

    line = tkchart.Line(
    master=chart, 
    line_style="dashed" 
)

  • style_type

    The style_type parameter is a tuple that contains two integer values, specifying the style of the dashes and dots used when the style is set to "dashed" or "dotted".

    For example:

    • If you set style_type to (20, 10), it means:
      • The width of each dash or size of each dot is 20 pixels.
      • The spacing between dashes or dots is 10 pixels.

    Note: In the "dotted" style, the size parameter is irrelevant as the dots are of fixed size determined by the style_type tuple.
    Note: In the "normal" style, the style_type parameter is do nothing.

    line = tkchart.Line(
    master=chart, 
    line_style="dashed", 
    line_style_type=(10,2) 
)

  • point_highlight

    The point_highlight parameter is used to control point highlight, enabling or disabling it.

    • Supported values:
      • "enabled": Enable point highlight.
      • "disabled": Disable point highlight.

  • point_highlight_size

    The point_highlight_size is used to set size of the highlight.

  • point_highlight_color

    The point_highlight_color used to control color of highlight.

    line = tkchart.Line(
    master=chart, 
    point_highlight="enabled", 
    point_highlight_color="#80CCFF", 
    point_highlight_size=8 
)

  • fill

    The fill parameter is utilized to control whether line fill is enabled or disabled.

    • Supported Values:
      • "enabled": Enable line fill.
      • "disabled": Disable line fill.

  • fill_color

    The fill_color parameter is used to specify the color for the fill.

    line = tkchart.Line(
    master=chart, 
    fill="enabled", 
    fill_color="#5D6DB6" 
)

Back to the Top | Usage Guide | Parameter Explanation | Whats New ?

Examples

Links

PyPi.org : tkchart

GitHub.com : tkchart