Repository: qtile/qtile

Issue:
fmt key better documentation?
### The issue:

I can't find anything in the documentation on how to format the float output of the OpenWeather widget. I tried searching for `fmt` everywhere but it's just `("fmt", "{}", "How to format the text")` .

### Required:

- [X] I have searched past issues to see if this bug has already been reported.


Discussion:
It's nothing to do with `fmt`. That's an overall wrapper for the final string. Typically, you'd leave it alone but you can add markup.

You actually want to edit `format` instead. Let's say your format string is `format='{location_city}: {temp}` you could try changing this to `format='{location_city}: {temp:.0f}` to remove the decimal point.
Thanks a lot. I'd appreciate some more documentation on fmt tho :)
> Thanks a lot. I'd appreciate some more documentation on fmt tho :)

I agree, but what would be a better description for it? Also, adding an example to it would probably make it way clearer.
> > Thanks a lot. I'd appreciate some more documentation on fmt tho :)
> 
> I agree, but what would be a better description for it? Also, adding an example to it would probably make it way clearer.

If I knew what fmt does, I would submit a PR, not write an issue :)
OK, I'll explain:

Widgets that display text typically inherit `base._TextBox` directly, or indirectly.

`base_TextBox` has a property called `formatted_text` which takes the text and basically does `self.fmt.format(text)`.

The output of this property is what is displayed in the widget.

So, if you're using, say, the `OpenWeather` widget and have it set up to show the temperature, leaving `fmt` as `{}` will make no difference to the output. However, if you set `fmt` to `The temperature is: {}` your widget will fill the curly brackets with the temperature.

`fmt` is therefore a way to add additional text, prefixes, markup etc to text based widget. It's particularly useful on those widgets where you can't edit the text. Take `CurrentScreen` for instance. That widget, by default, just shows the number of the screen. If you set `fmt` to `Current screen: {}` you now get that additional text in front of the screen number.

This allows you to add extra text to the widget without needing to use a separate `TextBox` widget to add more text.
Thanks!
How is this different from the `format` property used by widgets like battery?
Not every text widget has a `format` parameter (eg my example of `CurrentScreen`) in which case this is the only way to add extra text.

`fmt` is part of `base._TextBox` so *every* text widget inherits this. But, yes, if a widget *also* provides `format` then there's no real need to use `fmt` which is the point I made near the beginning of this thread.
So then why do we even have `format`?
Because it's *final* step for formatting text. It is separate to the *contents* of the widget which each widget defines separately.
Oh, yeah I understand. Thanks again!
Thank you, @elParaguayo!
While it looks like the confusion here has been resolved, it was a result of the poor documentation (the original issue), so perhaps that should still be addressed? Particularly the disinction between `fmt` and `format` for those widgets that have both.
Shall i reopen this?
It's OK, I have. I'm wondering how best to document this. Perhaps as @SweepingBishops says just an example, a note somewhere on the widget page explicitly mentioning both, using for instance the examples @elParaguayo gave. What do you think?
This line could be clearer:
https://github.com/qtile/qtile/blob/634a470a12e787a1a00fe7747059fc6a9de0201c/libqtile/widget/base.py#L389

And then we need something in the docs - maybe we add something about configuring widgets in the [Configuration](http://docs.qtile.org/en/stable/manual/config/index.html) page e.g. after `Screens` where we mention the `Bar`.
Maybe I should pick this one up...

Resolving patch:
diff --git a/libqtile/widget/base.py b/libqtile/widget/base.py
--- a/libqtile/widget/base.py
+++ b/libqtile/widget/base.py
@@ -386,7 +386,14 @@ class _TextBox(_Widget):
         ("foreground", "ffffff", "Foreground colour"),
         ("fontshadow", None, "font shadow color, default is None(no shadow)"),
         ("markup", True, "Whether or not to use pango markup"),
-        ("fmt", "{}", "How to format the text"),
+        (
+            "fmt",
+            "{}",
+            "To format the string returned by the widget. For example, if the clock widget \
+             returns '08:46' we can do fmt='time {}' do print 'time 08:46' on the widget. \
+             To format the individual strings like hour and minutes use the format paramater \
+             of the widget (if it has one)",
+        ),
         ("max_chars", 0, "Maximum number of characters to display in widget."),
     ]  # type: list[tuple[str, Any, str]]
 
diff --git a/libqtile/widget/bluetooth.py b/libqtile/widget/bluetooth.py
--- a/libqtile/widget/bluetooth.py
+++ b/libqtile/widget/bluetooth.py
@@ -32,9 +32,11 @@
 
 class Bluetooth(base._TextBox):
     """
-    Displays bluetooth status or connected device.
+    Displays bluetooth status for a particular connected device.
 
-    Uses dbus to communicate with the system bus.
+    (For example your bluetooth headphones.)
+
+    Uses dbus-next to communicate with the system bus.
 
     Widget requirements: dbus-next_.
 


Test patch: