Add docs for default url format.

examples/a_simple.pl

@@ -36,11 +36,6 @@
 
 
 # Write a hyperlink
-my $hyperlink_format = $workbook->add_format(
-    color     => 'blue',
-    underline => 1,
-);
-
-$worksheet->write( 10, 0, 'http://www.perl.com/', $hyperlink_format );
+$worksheet->write( 10, 0, 'http://www.perl.com/' );
 
 __END__

examples/demo.pl

@@ -37,12 +37,6 @@
     align => 'vcenter',
 );
 
-my $hyperlink_format = $workbook->add_format(
-    color => 'blue',
-    underline => 1,
-);
-
-
 my @headings = ( 'Features of Excel::Writer::XLSX', '' );
 $worksheet->write_row( 'A1', \@headings, $heading );
 
@@ -97,7 +91,7 @@
 # Hyperlinks
 #
 $worksheet->write( 'A9', "Hyperlinks" );
-$worksheet->write( 'B9', 'http://www.perl.com/', $hyperlink_format );
+$worksheet->write( 'B9', 'http://www.perl.com/' );
 
 
 #######################################################################

examples/hyperlink1.pl

@@ -23,14 +23,7 @@
 $worksheet->set_column( 'A:A', 30 );
 $worksheet->set_selection( 'B1' );
 
-
-# Add the standard url link format.
-my $url_format = $workbook->add_format(
-    color     => 'blue',
-    underline => 1,
-);
-
-# Add a sample format.
+# Add a user defined hyperlink format.
 my $red_format = $workbook->add_format(
     color     => 'red',
     bold      => 1,
@@ -45,12 +38,13 @@
 my $tip = 'Get the latest Perl news here.';
 
 
-# Write some hyperlinks
-$worksheet->write( 'A1', 'http://www.perl.com/', $url_format );
-$worksheet->write( 'A3', 'http://www.perl.com/', $url_format, $str );
-$worksheet->write( 'A5', 'http://www.perl.com/', $url_format, $str, $tip );
+# Write some hyperlinks. Unspecified or undefined format paraamters will be
+# replace with the defuault Excel hyperlink style.
+$worksheet->write( 'A1', 'http://www.perl.com/' );
+$worksheet->write( 'A3', 'http://www.perl.com/', undef, $str );
+$worksheet->write( 'A5', 'http://www.perl.com/', undef, $str, $tip );
 $worksheet->write( 'A7', 'http://www.perl.com/', $red_format );
-$worksheet->write( 'A9', 'mailto:jmcnamara@cpan.org', $url_format, 'Mail me' );
+$worksheet->write( 'A9', 'mailto:jmcnamara@cpan.org', undef, 'Mail me' );
 
 # Write a URL that isn't a hyperlink
 $worksheet->write_string( 'A11', 'http://www.perl.com/' );

examples/hyperlink2.pl

@@ -34,32 +34,23 @@
 my $ire_links      = $ireland->add_worksheet( 'Links' );
 my $ire_sales      = $ireland->add_worksheet( 'Sales' );
 my $ire_data       = $ireland->add_worksheet( 'Product Data' );
-my $ire_url_format = $ireland->add_format(
-    color     => 'blue',
-    underline => 1,
-);
+my $ire_url_format = $ireland->get_default_url_format();
 
 
 my $italy = Excel::Writer::XLSX->new( 'C:\Temp\Europe\Italy.xlsx' );
 
 my $ita_links      = $italy->add_worksheet( 'Links' );
 my $ita_sales      = $italy->add_worksheet( 'Sales' );
 my $ita_data       = $italy->add_worksheet( 'Product Data' );
-my $ita_url_format = $italy->add_format(
-    color     => 'blue',
-    underline => 1,
-);
+my $ita_url_format = $italy->get_default_url_format();
 
 
 my $china = Excel::Writer::XLSX->new( 'C:\Temp\Asia\China.xlsx' );
 
 my $cha_links      = $china->add_worksheet( 'Links' );
 my $cha_sales      = $china->add_worksheet( 'Sales' );
 my $cha_data       = $china->add_worksheet( 'Product Data' );
-my $cha_url_format = $china->add_format(
-    color     => 'blue',
-    underline => 1,
-);
+my $cha_url_format = $china->get_default_url_format();
 
 
 # Add an alternative format

lib/Excel/Writer/XLSX.pm

@@ -149,6 +149,7 @@ The Excel::Writer::XLSX module provides an object oriented interface to a new Ex
     set_1904()
     set_optimization()
     set_calc_mode()
+    get_default_url_format()
 
 If you are unfamiliar with object oriented interfaces or the way that they are implemented in Perl have a look at C<perlobj> and C<perltoot> in the main Perl documentation.
 
@@ -645,6 +646,18 @@ Excel will automatically re-calculate formulas except for tables.
 
 =back
 
+
+
+
+=head2 get_default_url_format()
+
+The C<get_default_url_format()> method gets a copy of the default url format used when a user defined format isn't specified with the worksheet C<write_url()> method. The format is the hyperlink style defined by Excel for the default theme:
+
+    my $url_format = $workbook->get_default_url_format();
+
+
+
+
 =head1 WORKSHEET METHODS
 
 A new worksheet is created by calling the C<add_worksheet()> method from a workbook object:
@@ -1209,42 +1222,40 @@ See also the date_time.pl program in the C<examples> directory of the distro.
 
 Write a hyperlink to a URL in the cell specified by C<$row> and C<$column>. The hyperlink is comprised of two elements: the visible label and the invisible link. The visible label is the same as the link unless an alternative label is specified. The C<$label> parameter is optional. The label is written using the C<write()> method. Therefore it is possible to write strings, numbers or formulas as labels.
 
-The C<$format> parameter is also optional, however, without a format the link won't look like a link.
-
-The suggested format is:
-
-    my $format = $workbook->add_format( color => 'blue', underline => 1 );
+The C<$format> parameter is also optional and the default Excel hyperlink style will be used if it isn't specified. If required you can access the default url format using the Workbook C<get_default_url_format> method:
 
-B<Note>, this behaviour is different from Spreadsheet::WriteExcel which provides a default hyperlink format if one isn't specified by the user.
+    my $url_format = $workbook->get_default_url_format();
 
 There are four web style URI's supported: C<http://>, C<https://>, C<ftp://> and C<mailto:>:
 
-    $worksheet->write_url( 0, 0, 'ftp://www.perl.org/',       $format );
-    $worksheet->write_url( 'A3', 'http://www.perl.com/',      $format );
-    $worksheet->write_url( 'A4', 'mailto:jmcnamara@cpan.org', $format );
+    $worksheet->write_url( 0, 0, 'ftp://www.perl.org/' );
+    $worksheet->write_url( 'A3', 'http://www.perl.com/' );
+    $worksheet->write_url( 'A4', 'mailto:jmcnamara@cpan.org' );
 
 You can display an alternative string using the C<$label> parameter:
 
-    $worksheet->write_url( 1, 0, 'http://www.perl.com/', $format, 'Perl' );
+    $worksheet->write_url( 1, 0, 'http://www.perl.com/', undef, 'Perl' );
 
 If you wish to have some other cell data such as a number or a formula you can overwrite the cell using another call to C<write_*()>:
 
     $worksheet->write_url( 'A1', 'http://www.perl.com/' );
 
     # Overwrite the URL string with a formula. The cell is still a link.
-    $worksheet->write_formula( 'A1', '=1+1', $format );
+    # Note the use of the default url format for consistency with other links.
+    my $url_format = $workbook->get_default_url_format();
+    $worksheet->write_formula( 'A1', '=1+1', $url_format );
 
 There are two local URIs supported: C<internal:> and C<external:>. These are used for hyperlinks to internal worksheet references or external workbook and worksheet references:
 
-    $worksheet->write_url( 'A6',  'internal:Sheet2!A1',              $format );
-    $worksheet->write_url( 'A7',  'internal:Sheet2!A1',              $format );
-    $worksheet->write_url( 'A8',  'internal:Sheet2!A1:B2',           $format );
-    $worksheet->write_url( 'A9',  q{internal:'Sales Data'!A1},       $format );
-    $worksheet->write_url( 'A10', 'external:c:\temp\foo.xlsx',       $format );
-    $worksheet->write_url( 'A11', 'external:c:\foo.xlsx#Sheet2!A1',  $format );
-    $worksheet->write_url( 'A12', 'external:..\foo.xlsx',            $format );
-    $worksheet->write_url( 'A13', 'external:..\foo.xlsx#Sheet2!A1',  $format );
-    $worksheet->write_url( 'A13', 'external:\\\\NET\share\foo.xlsx', $format );
+    $worksheet->write_url( 'A6',  'internal:Sheet2!A1' );
+    $worksheet->write_url( 'A7',  'internal:Sheet2!A1' );
+    $worksheet->write_url( 'A8',  'internal:Sheet2!A1:B2' );
+    $worksheet->write_url( 'A9',  q{internal:'Sales Data'!A1} );
+    $worksheet->write_url( 'A10', 'external:c:\temp\foo.xlsx' );
+    $worksheet->write_url( 'A11', 'external:c:\foo.xlsx#Sheet2!A1' );
+    $worksheet->write_url( 'A12', 'external:..\foo.xlsx' );
+    $worksheet->write_url( 'A13', 'external:..\foo.xlsx#Sheet2!A1' );
+    $worksheet->write_url( 'A13', 'external:\\\\NET\share\foo.xlsx' );
 
 All of the these URI types are recognised by the C<write()> method, see above.
 

lib/Excel/Writer/XLSX/Workbook.pm

@@ -1024,6 +1024,22 @@ sub set_calc_mode {
 }
 
 
+###############################################################################
+#
+# get_default_url_format()
+#
+# Get the default url format used when a user defined format isn't specified
+# with write_url(). The format is the hyperlink style defined by Excel for the
+# default theme.
+#
+sub get_default_url_format {
+
+    my $self    = shift;
+
+    return $self->{_default_url_format};
+}
+
+
 ###############################################################################
 #
 # _store_workbook()

lib/Excel/Writer/XLSX/Worksheet.pm

@@ -2682,7 +2682,7 @@ sub _escape_url {
 
 ###############################################################################
 #
-# write_url($row, $col, $url, $string, $format)
+# write_url($row, $col, $url, format, $string)
 #
 # Write a hyperlink. This is comprised of two elements: the visible label and
 # the invisible link. The visible label is the same as the link unless an
@@ -2712,18 +2712,19 @@ sub write_url {
     if ( @_ < 3 ) { return -1 }    # Check the number of args
 
 
-    # Reverse the order of $string and $format if necessary. We work on a copy
-    # in order to protect the callers args. We don't use "local @_" in case of
-    # perl50005 threads.
+    # Reverse the order of $string and $format if necessary, for backward
+    # compatibility. We work on a copy in order to protect the callers
+    # args. We don't use "local @_" in case of perl50005 threads.
     my @args = @_;
-    ( $args[3], $args[4] ) = ( $args[4], $args[3] ) if ref $args[3];
-
+    if (defined $args[3] and !ref $args[3]) {
+        ( $args[3], $args[4] ) = ( $args[4], $args[3] );
+    }
 
     my $row       = $args[0];    # Zero indexed row
     my $col       = $args[1];    # Zero indexed column
     my $url       = $args[2];    # URL string
-    my $str       = $args[3];    # Alternative label
-    my $xf        = $args[4];    # Cell format
+    my $xf        = $args[3];    # Cell format
+    my $str       = $args[4];    # Alternative label
     my $tip       = $args[5];    # Tool tip
     my $type      = 'l';         # XML data type
     my $link_type = 1;

t/regression/hyperlink28.t

@@ -10,7 +10,7 @@ use TestFunctions qw(_compare_xlsx_files _is_deep_diff);
 use strict;
 use warnings;
 
-use Test::More tests => 2;
+use Test::More tests => 3;
 
 ###############################################################################
 #
@@ -85,6 +85,36 @@ $workbook->close();
 _is_deep_diff( $got, $expected, $caption );
 
 
+
+
+###############################################################################
+#
+# Test3. Test with the workbook default format.
+#
+$workbook  = Excel::Writer::XLSX->new( $got_filename );
+$worksheet = $workbook->add_worksheet();
+$format    = $workbook->get_default_url_format();
+
+$worksheet->write_url( 'A1', 'http://www.perl.org/', $format);
+
+$workbook->close();
+
+
+###############################################################################
+#
+# Compare the generated and existing Excel files.
+#
+( $got, $expected, $caption ) = _compare_xlsx_files(
+
+    $got_filename,
+    $exp_filename,
+    $ignore_members,
+    $ignore_elements,
+);
+
+_is_deep_diff( $got, $expected, $caption );
+
+
 ###############################################################################
 #
 # Cleanup.