Rename Font::loadFromFile into Font::openFromFile

Similar renaming for Font::loadFromMemory and Font::loadFromStream.
The goal is to better express the need to keep the source available,
similar to Music::openFromFile for example.

doc/mainpage.hpp

@@ -25,7 +25,7 @@
 ///     sf::Sprite sprite(texture);
 ///
 ///     // Create a graphical text to display
-///     const auto font = sf::Font::loadFromFile("arial.ttf").value();
+///     const auto font = sf::Font::openFromFile("arial.ttf").value();
 ///     sf::Text text(font, "Hello SFML", 50);
 ///
 ///     // Load a music to play

examples/android/app/src/main/jni/main.cpp

@@ -92,7 +92,7 @@ int main(int argc, char* argv[])
     image.setPosition(sf::Vector2f(screen.size) / 2.f);
     image.setOrigin(sf::Vector2f(texture.getSize()) / 2.f);
 
-    const auto font = sf::Font::loadFromFile("tuffy.ttf").value();
+    const auto font = sf::Font::openFromFile("tuffy.ttf").value();
 
     sf::Text text(font, "Tap anywhere to move the logo.", 64);
     text.setFillColor(sf::Color::Black);

examples/cocoa/CocoaAppDelegate.mm

@@ -52,7 +52,7 @@ struct SFMLmainWindow
 
     std::filesystem::path resPath{[[[NSBundle mainBundle] resourcePath] tostdstring]};
     sf::RenderWindow      renderWindow;
-    sf::Font              font{sf::Font::loadFromFile(resPath / "tuffy.ttf").value()};
+    sf::Font              font{sf::Font::openFromFile(resPath / "tuffy.ttf").value()};
     sf::Text              text{font};
     sf::Texture           logo{sf::Texture::loadFromFile(resPath / "logo.png").value()};
     sf::Sprite            sprite{logo};

examples/island/Island.cpp

@@ -91,7 +91,7 @@ int main()
     sf::RenderWindow window(sf::VideoMode({windowWidth, windowHeight}), "SFML Island", sf::Style::Titlebar | sf::Style::Close);
     window.setVerticalSyncEnabled(true);
 
-    const auto font = sf::Font::loadFromFile("resources/tuffy.ttf").value();
+    const auto font = sf::Font::openFromFile("resources/tuffy.ttf").value();
 
     // Create all of our graphics resources
     sf::Text                  hudText(font);

examples/joystick/Joystick.cpp

@@ -93,8 +93,8 @@ int main()
     sf::RenderWindow window(sf::VideoMode({400, 775}), "Joystick", sf::Style::Close);
     window.setVerticalSyncEnabled(true);
 
-    // Load the text font
+    // Open the text font
-    const auto font = sf::Font::loadFromFile("resources/tuffy.ttf").value();
+    const auto font = sf::Font::openFromFile("resources/tuffy.ttf").value();
 
     // Set up our string conversion parameters
     sstr.precision(2);

examples/opengl/OpenGL.cpp

@@ -62,7 +62,7 @@ int main()
         const sf::Sprite background(backgroundTexture);
 
         // Create some text to draw on top of our OpenGL object
-        const auto font = sf::Font::loadFromFile(resourcesDir() / "tuffy.ttf").value();
+        const auto font = sf::Font::openFromFile(resourcesDir() / "tuffy.ttf").value();
 
         sf::Text text(font, "SFML / OpenGL demo");
         sf::Text sRgbInstructions(font, "Press space to toggle sRGB conversion");

examples/raw_input/RawInput.cpp

@@ -18,8 +18,8 @@ int main()
     sf::RenderWindow window(sf::VideoMode({800u, 600u}), "SFML Raw Mouse Input", sf::Style::Titlebar | sf::Style::Close);
     window.setVerticalSyncEnabled(true);
 
-    // Load the application font and pass it to the Effect class
+    // Open the application font and pass it to the Effect class
-    const auto font = sf::Font::loadFromFile("resources/tuffy.ttf").value();
+    const auto font = sf::Font::openFromFile("resources/tuffy.ttf").value();
 
     // Create the mouse position text
     sf::Text mousePosition(font, "", 20);

examples/shader/Shader.cpp

@@ -393,8 +393,8 @@ int main()
     sf::RenderWindow window(sf::VideoMode({800, 600}), "SFML Shader", sf::Style::Titlebar | sf::Style::Close);
     window.setVerticalSyncEnabled(true);
 
-    // Load the application font
+    // Open the application font
-    const auto font = sf::Font::loadFromFile("resources/tuffy.ttf").value();
+    const auto font = sf::Font::openFromFile("resources/tuffy.ttf").value();
 
     // Create the effects
     std::optional pixelateEffect   = tryLoadPixelate();

examples/sound_effects/SoundEffects.cpp

@@ -1063,8 +1063,8 @@ int main()
                             sf::Style::Titlebar | sf::Style::Close);
     window.setVerticalSyncEnabled(true);
 
-    // Load the application font and pass it to the Effect class
+    // Open the application font and pass it to the Effect class
-    const auto font = sf::Font::loadFromFile(resourcesDir() / "tuffy.ttf").value();
+    const auto font = sf::Font::openFromFile(resourcesDir() / "tuffy.ttf").value();
     Effect::setFont(font);
 
     // Create the effects

examples/tennis/Tennis.cpp

@@ -81,8 +81,8 @@ int main()
     ball.setFillColor(sf::Color::White);
     ball.setOrigin({ballRadius / 2.f, ballRadius / 2.f});
 
-    // Load the text font
+    // Open the text font
-    const auto font = sf::Font::loadFromFile(resourcesDir() / "tuffy.ttf").value();
+    const auto font = sf::Font::openFromFile(resourcesDir() / "tuffy.ttf").value();
 
     // Initialize the pause message
     sf::Text pauseMessage(font);

include/SFML/Graphics/Font.hpp

@@ -74,7 +74,7 @@ public:
     };
 
     ////////////////////////////////////////////////////////////
-    /// \brief Load the font from a file
+    /// \brief Open the font from a file
     ///
     /// The supported font formats are: TrueType, Type 1, CFF,
     /// OpenType, SFNT, X11 PCF, Windows FNT, BDF, PFR and Type 42.
@@ -84,59 +84,55 @@ public:
     ///
     /// \warning SFML cannot preload all the font data in this
     /// function, so the file has to remain accessible until
-    /// the sf::Font object loads a new font or is destroyed.
+    /// the sf::Font object is destroyed.
     ///
     /// \param filename Path of the font file to load
     ///
-    /// \return Font if loading succeeded, `std::nullopt` if it failed
+    /// \return Font if opening succeeded, `std::nullopt` if it failed
     ///
-    /// \see loadFromMemory, loadFromStream
+    /// \see openFromMemory, openFromStream
     ///
     ////////////////////////////////////////////////////////////
-    [[nodiscard]] static std::optional<Font> loadFromFile(const std::filesystem::path& filename);
+    [[nodiscard]] static std::optional<Font> openFromFile(const std::filesystem::path& filename);
 
     ////////////////////////////////////////////////////////////
-    /// \brief Load the font from a file in memory
+    /// \brief Open the font from a file in memory
     ///
     /// The supported font formats are: TrueType, Type 1, CFF,
     /// OpenType, SFNT, X11 PCF, Windows FNT, BDF, PFR and Type 42.
     ///
     /// \warning SFML cannot preload all the font data in this
     /// function, so the buffer pointed by \a data has to remain
-    /// valid until the sf::Font object loads a new font or
+    /// valid until the sf::Font object is destroyed.
-    /// is destroyed.
     ///
     /// \param data        Pointer to the file data in memory
     /// \param sizeInBytes Size of the data to load, in bytes
     ///
-    /// \return Font if loading succeeded, `std::nullopt` if it failed
+    /// \return Font if opening succeeded, `std::nullopt` if it failed
     ///
-    /// \see loadFromFile, loadFromStream
+    /// \see openFromFile, openFromStream
     ///
     ////////////////////////////////////////////////////////////
-    [[nodiscard]] static std::optional<Font> loadFromMemory(const void* data, std::size_t sizeInBytes);
+    [[nodiscard]] static std::optional<Font> openFromMemory(const void* data, std::size_t sizeInBytes);
 
     ////////////////////////////////////////////////////////////
-    /// \brief Load the font from a custom stream
+    /// \brief Open the font from a custom stream
     ///
     /// The supported font formats are: TrueType, Type 1, CFF,
     /// OpenType, SFNT, X11 PCF, Windows FNT, BDF, PFR and Type 42.
-    /// Warning: SFML cannot preload all the font data in this
-    /// function, so the contents of \a stream have to remain
-    /// valid as long as the font is used.
     ///
     /// \warning SFML cannot preload all the font data in this
     /// function, so the stream has to remain accessible until
-    /// the sf::Font object loads a new font or is destroyed.
+    /// the sf::Font object is destroyed.
     ///
     /// \param stream Source stream to read from
     ///
-    /// \return Font if loading succeeded, `std::nullopt` if it failed
+    /// \return Font if opening succeeded, `std::nullopt` if it failed
     ///
-    /// \see loadFromFile, loadFromMemory
+    /// \see openFromFile, openFromMemory
     ///
     ////////////////////////////////////////////////////////////
-    [[nodiscard]] static std::optional<Font> loadFromStream(InputStream& stream);
+    [[nodiscard]] static std::optional<Font> openFromStream(InputStream& stream);
 
     ////////////////////////////////////////////////////////////
     /// \brief Get the font information
@@ -401,11 +397,11 @@ private:
 /// \class sf::Font
 /// \ingroup graphics
 ///
-/// Fonts can be loaded from a file, from memory or from a custom
+/// Fonts can be opened from a file, from memory or from a custom
 /// stream, and supports the most common types of fonts. See
-/// the loadFromFile function for the complete list of supported formats.
+/// the openFromFile function for the complete list of supported formats.
 ///
-/// Once it is loaded, a sf::Font instance provides three
+/// Once it is opened, a sf::Font instance provides three
 /// types of information about the font:
 /// \li Global metrics, such as the line spacing
 /// \li Per-glyph metrics, such as bounding box or kerning
@@ -433,8 +429,8 @@ private:
 ///
 /// Usage example:
 /// \code
-/// // Load a new font
+/// // Open a new font
-/// const auto font = sf::Font::loadFromFile("arial.ttf").value();
+/// const auto font = sf::Font::openFromFile("arial.ttf").value();
 ///
 /// // Create a text which uses our font
 /// sf::Text text1(font);
@@ -447,7 +443,7 @@ private:
 /// text2.setStyle(sf::Text::Italic);
 /// \endcode
 ///
-/// Apart from loading font files, and passing them to instances
+/// Apart from opening font files, and passing them to instances
 /// of sf::Text, you should normally not have to deal directly
 /// with this class. However, it may be useful to access the
 /// font metrics or rasterized glyphs for advanced usage.

include/SFML/Graphics/RenderWindow.hpp

@@ -268,7 +268,7 @@ private:
 /// // Create a sprite and a text to display
 /// const auto texture = sf::Texture::loadFromFile("circle.png").value();
 /// sf::Sprite sprite(texture);
-/// const auto font = sf::Font::loadFromFile("arial.ttf").value();
+/// const auto font = sf::Font::openFromFile("arial.ttf").value();
 /// sf::Text text(font);
 /// ...
 ///

include/SFML/Graphics/Text.hpp

@@ -468,8 +468,8 @@ private:
 ///
 /// Usage example:
 /// \code
-/// // Load a font
+/// // Open a font
-/// const auto font = sf::Font::loadFromFile("arial.ttf").value();
+/// const auto font = sf::Font::openFromFile("arial.ttf").value();
 ///
 /// // Create a text
 /// sf::Text text(font, "hello");

src/SFML/Graphics/Font.cpp

@@ -129,7 +129,7 @@ Font::Font(std::shared_ptr<FontHandles>&& fontHandles, std::string&& familyName)
 
 
 ////////////////////////////////////////////////////////////
-std::optional<Font> Font::loadFromFile(const std::filesystem::path& filename)
+std::optional<Font> Font::openFromFile(const std::filesystem::path& filename)
 {
 #ifndef SFML_SYSTEM_ANDROID
 
@@ -173,7 +173,7 @@ std::optional<Font> Font::loadFromFile(const std::filesystem::path& filename)
 #else
 
     auto stream = std::make_shared<priv::ResourceStream>(filename);
-    auto font   = loadFromStream(*stream);
+    auto font   = openFromStream(*stream);
     if (font)
         font->m_stream = std::move(stream);
     return font;
@@ -183,7 +183,7 @@ std::optional<Font> Font::loadFromFile(const std::filesystem::path& filename)
 
 
 ////////////////////////////////////////////////////////////
-std::optional<Font> Font::loadFromMemory(const void* data, std::size_t sizeInBytes)
+std::optional<Font> Font::openFromMemory(const void* data, std::size_t sizeInBytes)
 {
     auto fontHandles = std::make_shared<FontHandles>();
 
@@ -228,7 +228,7 @@ std::optional<Font> Font::loadFromMemory(const void* data, std::size_t sizeInByt
 
 
 ////////////////////////////////////////////////////////////
-std::optional<Font> Font::loadFromStream(InputStream& stream)
+std::optional<Font> Font::openFromStream(InputStream& stream)
 {
     auto fontHandles = std::make_shared<FontHandles>();
 

test/Graphics/Font.test.cpp

@@ -22,16 +22,16 @@ TEST_CASE("[Graphics] sf::Font", runDisplayTests())
         STATIC_CHECK(std::is_move_assignable_v<sf::Font>);
     }
 
-    SECTION("loadFromFile()")
+    SECTION("openFromFile()")
     {
         SECTION("Invalid filename")
         {
-            CHECK(!sf::Font::loadFromFile("does/not/exist.ttf"));
+            CHECK(!sf::Font::openFromFile("does/not/exist.ttf"));
         }
 
-        SECTION("Successful load")
+        SECTION("Valid file")
         {
-            const auto font = sf::Font::loadFromFile("Graphics/tuffy.ttf").value();
+            const auto font = sf::Font::openFromFile("Graphics/tuffy.ttf").value();
             CHECK(font.getInfo().family == "Tuffy");
             const auto& glyph = font.getGlyph(0x45, 16, false);
             CHECK(glyph.advance == 9);
@@ -56,19 +56,19 @@ TEST_CASE("[Graphics] sf::Font", runDisplayTests())
         }
     }
 
-    SECTION("loadFromMemory()")
+    SECTION("openFromMemory()")
     {
         SECTION("Invalid data and size")
         {
-            CHECK(!sf::Font::loadFromMemory(nullptr, 1));
+            CHECK(!sf::Font::openFromMemory(nullptr, 1));
             const std::byte testByte{0xCD};
-            CHECK(!sf::Font::loadFromMemory(&testByte, 0));
+            CHECK(!sf::Font::openFromMemory(&testByte, 0));
         }
 
-        SECTION("Successful load")
+        SECTION("Valid data")
         {
             const auto memory = loadIntoMemory("Graphics/tuffy.ttf");
-            const auto font   = sf::Font::loadFromMemory(memory.data(), memory.size()).value();
+            const auto font   = sf::Font::openFromMemory(memory.data(), memory.size()).value();
             CHECK(font.getInfo().family == "Tuffy");
             const auto& glyph = font.getGlyph(0x45, 16, false);
             CHECK(glyph.advance == 9);
@@ -93,10 +93,10 @@ TEST_CASE("[Graphics] sf::Font", runDisplayTests())
         }
     }
 
-    SECTION("loadFromStream()")
+    SECTION("openFromStream()")
     {
         auto       stream = sf::FileInputStream::open("Graphics/tuffy.ttf").value();
-        const auto font   = sf::Font::loadFromStream(stream).value();
+        const auto font   = sf::Font::openFromStream(stream).value();
         CHECK(font.getInfo().family == "Tuffy");
         const auto& glyph = font.getGlyph(0x45, 16, false);
         CHECK(glyph.advance == 9);
@@ -122,7 +122,7 @@ TEST_CASE("[Graphics] sf::Font", runDisplayTests())
 
     SECTION("Set/get smooth")
     {
-        auto font = sf::Font::loadFromFile("Graphics/tuffy.ttf").value();
+        auto font = sf::Font::openFromFile("Graphics/tuffy.ttf").value();
         font.setSmooth(false);
         CHECK(!font.isSmooth());
     }

test/Graphics/Text.test.cpp

@@ -21,7 +21,7 @@ TEST_CASE("[Graphics] sf::Text", runDisplayTests())
         STATIC_CHECK(std::is_nothrow_move_assignable_v<sf::Text>);
     }
 
-    const auto font = sf::Font::loadFromFile("Graphics/tuffy.ttf").value();
+    const auto font = sf::Font::openFromFile("Graphics/tuffy.ttf").value();
 
     SECTION("Construction")
     {
@@ -87,7 +87,7 @@ TEST_CASE("[Graphics] sf::Text", runDisplayTests())
     SECTION("Set/get font")
     {
         sf::Text   text(font);
-        const auto otherFont = sf::Font::loadFromFile("Graphics/tuffy.ttf").value();
+        const auto otherFont = sf::Font::openFromFile("Graphics/tuffy.ttf").value();
         text.setFont(otherFont);
         CHECK(&text.getFont() == &otherFont);
     }

tools/xcode/templates/SFML/SFML App.xctemplate/main.cpp

@@ -34,7 +34,7 @@ int main()
     sf::Sprite sprite(texture);
 
     // Create a graphical text to display
-    const auto font = sf::Font::loadFromFile(resourcePath() / "tuffy.ttf").value();
+    const auto font = sf::Font::openFromFile(resourcePath() / "tuffy.ttf").value();
     sf::Text   text(font, "Hello SFML", 50);
     text.setFillColor(sf::Color::Black);
 

tools/xcode/templates/SFML/SFML CLT.xctemplate/main.cpp

@@ -32,7 +32,7 @@ int main()
     sf::Sprite sprite(texture);
 
     // Create a graphical text to display
-    const auto font = sf::Font::loadFromFile("tuffy.ttf").value();
+    const auto font = sf::Font::openFromFile("tuffy.ttf").value();
     sf::Text   text(font, "Hello SFML", 50);
     text.setFillColor(sf::Color::Black);